docs: resolve CodeRabbit nitpick comments

- Add cross-reference from comparison doc to PROGRESS.md roadmap
- Clarify good vs bad examples in code-analyst.md
- Add forward reference to context_bootstrap.md from code-analyst.md
- Make decision sources explicit with line numbers in PROGRESS.md
- Add note about question scope in generate-context.md
- Add migration impact note to research-synthesis.md
- Reduce word repetition in decision rationale questions
- Fix compound modifier hyphenation (Medium-and-Low-Confidence)

Co-authored-by: Gregg Coppen <[email protected]>

Author: github-actions[bot]

docs/research/codebase-context/claude-code-feature-dev-comparison.md

@@ -772,6 +772,9 @@ Create `docs/workflow.md`:
 
 ## Implementation Priority
 
+See [docs/roadmap/PROGRESS.md](../../roadmap/PROGRESS.md) for detailed Phase 2 planning,
+effort estimates, and acceptance criteria.
+
 ### Sprint 1: Critical Gaps (Week 1)
 
 - [ ] Enhance `generate-spec` with mandatory clarifying phase

docs/research/codebase-context/code-analyst.md

@@ -6,6 +6,9 @@ description: Specialized agent for analyzing source code to discover what the sy
 
 # Code Analyst
 
+You are a specialized code analysis agent, part of the context_bootstrap pattern
+(see [context_bootstrap.md](./context_bootstrap.md) for orchestration details).
+
 You are a Code Analyst with expertise in reverse-engineering systems through source code analysis. Your job is to discover what a system does and how it's built by analyzing its implementation.
 
 ## Your Job
@@ -177,6 +180,8 @@ Return a structured summary that the manager can use:
 ### Output Examples: Good vs Bad
 
 **Good Analysis** (focuses on what exists and works):
+
+This demonstrates: specific evidence, confidence marking, working features only
 ```markdown
 ### System Capabilities
 - REST API exposes catalog search, item detail, and purchase flows (Entry point: `services/api/catalog/routes.ts#L12`)
@@ -202,6 +207,8 @@ Return a structured summary that the manager can use:
 
 **Bad Analysis** (too detailed, judges code, lists missing features):
 
+Problems: includes code quality judgments, specific versions, missing features, internal models
+
 ```markdown
 ### System Capabilities
 - REST API with 5 endpoints (GOOD CODE QUALITY, well-tested)

docs/research/codebase-context/research-synthesis.md

@@ -276,6 +276,14 @@ Following Information Analyst patterns:
 - Save to `/tasks/[n]-context-[name].md`
 ```
 
+### Migration Impact
+
+This restructuring will change the output format and process. Users with existing
+codebase context documents should:
+- **Still valid:** All file:line citations remain accurate
+- **May need updating:** If they reference specific sections, page numbers may shift
+- **Recommended:** Regenerate context analyses using the new prompt format for consistency
+
 ---
 
 ### 🔴 HIGH PRIORITY: Add Evidence Citation Standards

docs/roadmap/PROGRESS.md

@@ -620,7 +620,8 @@ The following improvements are **documented and ready to implement** but will be
 
 **Decision:** Require file:line for code, path#heading for docs, dated quotes for users
 **Rationale:** Provides traceability and accountability for all findings
-**Source:** code-analyst.md + information-analyst.md patterns
+**Source:** code-analyst.md (lines 267-273, Key Principles),
+          information-analyst.md (lines 151-159, Key Principles)
 
 ### Decision 2: Confidence Levels
 
@@ -638,7 +639,8 @@ The following improvements are **documented and ready to implement** but will be
 
 **Decision:** Replace batch questionnaires with short focused rounds
 **Rationale:** Better user engagement, more thoughtful answers
-**Source:** context_bootstrap.md + Claude Code Phase 3 pattern
+**Source:** context_bootstrap.md (lines 38-42, Interactive Dialog principle),
+          Claude Code Phase 3 (see docs/research/codebase-context/claude-code-feature-dev-comparison.md, lines 66-87)
 
 ### Decision 5: Mandatory Clarifying Phase
 

prompts/generate-context.md

@@ -198,7 +198,7 @@ Categorize every finding by confidence level:
 - If no code references found → Start with Low Confidence
 - If docs are >6 months old without code confirmation → Maximum Medium Confidence
 
-### Always Flag Medium and Low Confidence Items for User Validation
+### Always Flag Medium- and Low-Confidence Items for User Validation
 
 ## Process
 
@@ -261,6 +261,9 @@ Automatically detect and analyze:
 
 #### Questions for User (Short - 3 questions max)
 
+**Important:** Keep questions brief and focused. Extended questionnaires reduce engagement
+and response quality. You'll ask follow-up questions in Phase 5 based on these answers.
+
 1. **Scope:** Should I analyze the entire codebase, or focus on specific components? If specific, which ones?
 
 2. **Purpose:** What's the primary reason for this analysis?
@@ -319,9 +322,8 @@ Find and catalog:
 
 - Why was [technology X] chosen?
 - Why [pattern Y] over alternatives?
-- What constraints drove decisions?
-- What trade-offs were considered?
-- What problems were these choices solving?
+- What constraints or trade-offs influenced these decisions?
+- What problems did these choices solve?
 
 **For each rationale found:**