brownfield-chat

/brownfield-chat — Natural Language Q&A

Purpose

Answer any structural, historical, or architectural question about the codebase without reading raw source files.

Trigger

• "What does X do?"
• "How does data flow from A to B?"
• "What breaks if I change this file?"
• "Which files handle authentication?"
• "What's the relationship between X and Y?"

Type: /brownfield-chat <question>

---

Steps

1. Understand the question

Parse the user's question to extract:

• Entity: which file, module, or pattern they're asking about (X, A, B, authentication, etc.)
• Relationship type: "what does", "how does", "what breaks", "which files", "relationship"
• Scope: single file, module, cross-module, or whole codebase

2. Search the codebase via DB

const queries = require('./.claude/query-helpers.js');
const results = queries.searchFiles(entityName);

This returns top matching files with full context:

• file_path, summary, purpose
• role, riskScore, importedByCount, importCount
• blastRadius (transitive dependents)
• entryPointConfidence

Return top 5 matching files.

3. For detailed file context, load full summary

const summary = queries.getFileSummary(dbPath, filePath);

Returns:

• filePath, lang, summary, purpose, primaryRole
• riskScore, band
• importedByCount, importCount (fan-in/fan-out)
• bugFixCommits, totalCommits
• isDeadFile, isCircularDep
• entryPointConfidence, dangerReason
• blastRadius (transitive impacts)

4. Answer the question

For "what does X do?"

Combine the file summary + purpose + role to answer in 2-3 sentences. Example: "auth.js is an Entry file (confidence 85%) that validates user credentials and manages JWT tokens. Imported by 8 files (api.js, middleware, routes). Risk score: 45 (Moderate)."

For "how does data flow from A to B?"

Use the import graph from file summaries to trace paths. If path exists: list it step-by-step. If no direct path: show closest path or note that they're unrelated.