From 37582f8fca1cb7d987f927fc9f438220ed60801f Mon Sep 17 00:00:00 2001 From: min-k-khant <102896221+min-hinthar@users.noreply.github.com> Date: Fri, 27 Feb 2026 10:59:15 -0800 Subject: [PATCH] feat: code-aware discuss phase with codebase scouting (#727) Add lightweight codebase scanning before gray area identification: - New scout_codebase step checks for existing maps or does targeted grep - Gray areas annotated with code context (existing components, patterns) - Discussion options informed by what already exists in the codebase - Context7 integration for library-specific questions - CONTEXT.md template includes code_context section Co-authored-by: Claude Opus 4.6 --- commands/gsd/discuss-phase.md | 13 +-- get-shit-done/templates/context.md | 14 ++++ get-shit-done/workflows/discuss-phase.md | 101 +++++++++++++++++++---- 3 files changed, 109 insertions(+), 19 deletions(-) diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md index dbeb2a417..cdfddce02 100644 --- a/commands/gsd/discuss-phase.md +++ b/commands/gsd/discuss-phase.md @@ -10,6 +10,8 @@ allowed-tools: - Grep - AskUserQuestion - Task + - mcp__context7__resolve-library-id + - mcp__context7__query-docs --- @@ -38,11 +40,12 @@ Context files are resolved in-workflow using `init phase-op` and roadmap/state t 1. Validate phase number (error if missing or not in roadmap) 2. Check if CONTEXT.md exists (offer update/view/skip if yes) -3. **Analyze phase** — Identify domain and generate phase-specific gray areas -4. **Present gray areas** — Multi-select: which to discuss? (NO skip option) -5. **Deep-dive each area** — 4 questions per area, then offer more/next -6. **Write CONTEXT.md** — Sections match areas discussed -7. Offer next steps (research or plan) +3. **Scout codebase** — Find reusable assets, patterns, and integration points +4. **Analyze phase** — Identify domain and generate code-informed gray areas +5. **Present gray areas** — Multi-select: which to discuss? (NO skip option) +6. **Deep-dive each area** — 4 questions per area, code-informed options, Context7 for library choices +7. **Write CONTEXT.md** — Sections match areas discussed + code_context section +8. Offer next steps (research or plan) **CRITICAL: Scope guardrail** - Phase boundary from ROADMAP.md is FIXED diff --git a/get-shit-done/templates/context.md b/get-shit-done/templates/context.md index 574e2e490..eed462bac 100644 --- a/get-shit-done/templates/context.md +++ b/get-shit-done/templates/context.md @@ -54,6 +54,20 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem + +## Existing Code Insights + +### Reusable Assets +- [Component/hook/utility]: [How it could be used in this phase] + +### Established Patterns +- [Pattern]: [How it constrains/enables this phase] + +### Integration Points +- [Where new code connects to existing system] + + + ## Deferred Ideas diff --git a/get-shit-done/workflows/discuss-phase.md b/get-shit-done/workflows/discuss-phase.md index 1b9596dac..b3ef81055 100644 --- a/get-shit-done/workflows/discuss-phase.md +++ b/get-shit-done/workflows/discuss-phase.md @@ -165,30 +165,73 @@ If "Continue and replan after": Continue to analyze_phase. If "View existing plans": Display plan files, then offer "Continue" / "Cancel". If "Cancel": Exit workflow. -**If `has_plans` is false:** Continue to analyze_phase. +**If `has_plans` is false:** Continue to scout_codebase. + + + +Lightweight scan of existing code to inform gray area identification and discussion. Uses ~10% context — acceptable for an interactive session. + +**Step 1: Check for existing codebase maps** +```bash +ls .planning/codebase/*.md 2>/dev/null +``` + +**If codebase maps exist:** Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract: +- Reusable components/hooks/utilities +- Established patterns (state management, styling, data fetching) +- Integration points (where new code would connect) + +Skip to Step 3 below. + +**Step 2: If no codebase maps, do targeted grep** + +Extract key terms from the phase goal (e.g., "feed" → "post", "card", "list"; "auth" → "login", "session", "token"). + +```bash +# Find files related to phase goal terms +grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 + +# Find existing components/hooks +ls src/components/ 2>/dev/null +ls src/hooks/ 2>/dev/null +ls src/lib/ src/utils/ 2>/dev/null +``` + +Read the 3-5 most relevant files to understand existing patterns. + +**Step 3: Build internal codebase_context** + +From the scan, identify: +- **Reusable assets** — existing components, hooks, utilities that could be used in this phase +- **Established patterns** — how the codebase does state management, styling, data fetching +- **Integration points** — where new code would connect (routes, nav, providers) +- **Creative options** — approaches the existing architecture enables or constrains + +Store as internal `` for use in analyze_phase and present_gray_areas. This is NOT written to a file — it's used within this session only. -Analyze the phase to identify gray areas worth discussing. +Analyze the phase to identify gray areas worth discussing. **Use codebase_context from scout step to ground the analysis.** **Read the phase description from ROADMAP.md and determine:** 1. **Domain boundary** — What capability is this phase delivering? State it clearly. -2. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation. +2. **Gray areas by category** — For each relevant category (UI, UX, Behavior, Empty States, Content), identify 1-2 specific ambiguities that would change implementation. **Annotate with code context where relevant** (e.g., "You already have a Card component" or "No existing pattern for this"). 3. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the phase may not need discussion. **Output your analysis internally, then present to user.** -Example analysis for "Post Feed" phase: +Example analysis for "Post Feed" phase (with code context): ``` Domain: Displaying posts from followed users +Existing: Card component (src/components/ui/Card.tsx), useInfiniteQuery hook, Tailwind CSS Gray areas: -- UI: Layout style (cards vs timeline vs grid) -- UI: Information density (full posts vs previews) -- Behavior: Loading pattern (infinite scroll vs pagination) -- Empty State: What shows when no posts exist +- UI: Layout style (cards vs timeline vs grid) — Card component exists with shadow/rounded variants +- UI: Information density (full posts vs previews) — no existing density patterns +- Behavior: Loading pattern (infinite scroll vs pagination) — useInfiniteQuery already set up +- Empty State: What shows when no posts exist — EmptyState component exists in ui/ - Content: What metadata displays (time, author, reactions count) ``` @@ -210,17 +253,23 @@ We'll clarify HOW to implement this. - question: "Which areas do you want to discuss for [phase name]?" - options: Generate 3-4 phase-specific gray areas, each with: - "[Specific area]" (label) — concrete, not generic - - [1-2 questions this covers] (description) + - [1-2 questions this covers + code context annotation] (description) - **Highlight the recommended choice with brief explanation why** +**Code context annotations:** When the scout found relevant existing code, annotate the gray area description: +``` +☐ Layout style — Cards vs list vs timeline? + (You already have a Card component with shadow/rounded variants. Reusing it keeps the app consistent.) +``` + **Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices. -**Examples by domain:** +**Examples by domain (with code context):** For "Post Feed" (visual feature): ``` -☐ Layout style — Cards vs list vs timeline? Information density? -☐ Loading behavior — Infinite scroll or pagination? Pull to refresh? +☐ Layout style — Cards vs list vs timeline? (Card component exists with variants) +☐ Loading behavior — Infinite scroll or pagination? (useInfiniteQuery hook available) ☐ Content ordering — Chronological, algorithmic, or user choice? ☐ Post metadata — What info per post? Timestamps, reactions, author? ``` @@ -262,7 +311,15 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft - header: "[Area]" (max 12 chars — abbreviate if needed) - question: Specific decision for this area - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically), with the recommended choice highlighted and brief explanation why + - **Annotate options with code context** when relevant: + ``` + "How should posts be displayed?" + - Cards (reuses existing Card component — consistent with Messages) + - List (simpler, would be a new pattern) + - Timeline (needs new Timeline component — none exists yet) + ``` - Include "You decide" as an option when reasonable — captures Claude discretion + - **Context7 for library choices:** When a gray area involves library selection (e.g., "magic links" → query next-auth docs) or API approach decisions, use `mcp__context7__*` tools to fetch current documentation and inform the options. Don't use Context7 for every question — only when library-specific knowledge improves the options. 3. **After 4 questions, check:** - header: "[Area]" (max 12 chars) @@ -346,6 +403,20 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}" + +## Existing Code Insights + +### Reusable Assets +- [Component/hook/utility]: [How it could be used in this phase] + +### Established Patterns +- [Pattern]: [How it constrains/enables this phase] + +### Integration Points +- [Where new code connects to existing system] + + + ## Specific Ideas @@ -531,11 +602,13 @@ Route to `confirm_creation` step (existing behavior — show manual next steps). - Phase validated against roadmap -- Gray areas identified through intelligent analysis (not generic questions) +- Codebase scouted for reusable assets, patterns, and integration points +- Gray areas identified through intelligent analysis with code context annotations - User selected which areas to discuss -- Each selected area explored until user satisfied +- Each selected area explored until user satisfied (with code-informed options) - Scope creep redirected to deferred ideas - CONTEXT.md captures actual decisions, not vague vision +- CONTEXT.md includes code_context section with reusable assets and patterns - Deferred ideas preserved for future phases - STATE.md updated with session info - User knows next steps