Documentation Search

Search the internal knowledge base using RAG (Retrieval-Augmented Generation) to find relevant runbooks, architecture docs, ADRs, and best practices.

Instructions

Phase 1: Query Understanding

1. •Parse the user's intent:
   • •Are they looking for a specific document (e.g., "deployment runbook")?
   • •Are they asking a question the docs can answer (e.g., "how do we handle rollbacks?")?
   • •Are they exploring a topic (e.g., "what do we know about A2A protocol?")?
2. •Formulate search queries:
   • •Extract key terms from the user's question
   • •Generate 2-3 variant queries to improve recall
   • •Include relevant synonyms (e.g., "deploy" = "release" = "ship")

Phase 2: Knowledge Base Search (RAG Agent)

1. •Search across document sources:
   • •Architecture Decision Records (ADRs) in docs/docs/changes/
   • •Spec Kit documents in .specify/specs/
   • •Runbooks and operational guides
   • •README files and inline documentation
   • •Confluence pages (if Confluence agent available)
   • •Backstage TechDocs (if Backstage agent available)
2. •Rank results by relevance:
   • •Exact keyword matches ranked highest
   • •Semantic similarity for conceptual matches
   • •Recency as a tiebreaker (newer docs preferred)

Phase 3: Answer Synthesis

1. •Direct answer: If the docs contain a clear answer, provide it directly
2. •Compiled answer: If information is spread across multiple docs, synthesize
3. •Source attribution: Always cite which document(s) the answer came from
4. •Gaps identified: Note if the question is only partially answered

Output Format

## Documentation Search Results

**Query**: "How do we handle database migrations?"

### Answer
Based on the internal documentation, database migrations follow this process:

1. Create a migration script using Alembic (see Runbook RB-023)
2. Test in staging environment first (required per ADR-008)
3. Run during the maintenance window defined in the on-call calendar
4. Verify with rollback script before marking complete

### Sources
| Document | Type | Relevance | Last Updated |
|----------|------|-----------|--------------|
| RB-023: Database Migration Runbook | Runbook | High | 2026-01-15 |
| ADR-008: Database Schema Changes | ADR | Medium | 2025-11-20 |
| .specify/specs/db-migration-v2.md | Spec | Medium | 2026-02-01 |

### Key Excerpts
> From **RB-023**: "Always run `alembic upgrade head --sql` first to preview
> the migration SQL before applying. Never run migrations during peak hours."

> From **ADR-008**: "We chose Alembic over Django migrations because our
> services are not Django-based and Alembic provides better raw SQL support."

### Related Topics
- Rollback procedures (see RB-024)
- Schema versioning strategy (see ADR-008)
- Testing database changes (see .specify/specs/db-testing.md)

Examples

• •"Search our knowledge base for deployment best practices"
• •"How do we handle rollbacks?"
• •"Find the runbook for EKS cluster upgrades"
• •"What ADRs do we have about streaming?"
• •"Show me the architecture documentation for the multi-agent system"
• •"What's our convention for Helm chart versioning?"

Guidelines

• •Always cite sources - never present information without attribution
• •If no relevant documents are found, say so clearly and suggest:
  • •Creating the missing documentation
  • •Which team might have the tribal knowledge
  • •Alternative search terms to try
• •Prefer internal documentation over general knowledge when both exist
• •For runbooks, include the full procedure steps rather than just linking
• •For ADRs, include the decision context and alternatives considered
• •Flag outdated documentation (>6 months old) with a freshness warning
• •If Confluence or Backstage agents are available, search those sources too
• •Distinguish between authoritative docs (ADRs, runbooks) and informal docs (notes, comments)