Codebase Awareness & Discovery

CRITICAL: Deep Discovery

Before proposing a PRD, technical plan, or new feature implementation, you MUST perform a deep discovery of the existing codebase.

1. •Never Assume Greenfield: Even if it's the start of a conversation, assume the user might have already started.
2. •Verify via Content, Not Just Names: Don't just dir or ls. Open core files (e.g., app/_layout.tsx, index.tsx, package.json, lib/) to understand existing logic.
3. •Map Existing Features: Create an internal mental map (or state in your thoughts) of:
   • •What screens are already built?
   • •What API clients/services are already initialized?
   • •What data schemas are being used?
4. •Fit, Don't Replace: New features must fit into the existing architecture. If the user asks for a feature that is 50% done, your plan must be "Complete the X feature" rather than "Implement the X feature".
5. •The Truthiness Check: Before recommending a task as "Active" or "Next", you MUST verify its status against three sources:
   • •Local State: Check for existing spec files in specs/.
   • •GitHub State: Run gh issue list --state closed AND gh issue list --state open (the default gh issue list is insufficient on its own).
   • •Git History: Run git log --grep="issue-number" or git log --oneline -50 to see if commits related to the task already exist in main.
   • •CRITICAL: If a spec file exists but the code and issue are complete, DELETE the spec file to prevent "zombie" feature drift.
6. •The Ghost Check (Anti-Hallucination):
   • •Concept: GitHub Issues are often stale. The Code is the only truth.
   • •Action: Before planning a feature, run a surgical search for the files that would exist if it were done (e.g., find_by_name "login", grep_search "AuthService").
   • •Verdict: If the code exists, the Issue is wrong. Close the Issue; do NOT duplicate the code.

Workflow: The "Pre-Plan" Audit

Whenever the /plan workflow or a similar "what should we do next" request is triggered:

• •Step 1: Run ls -R or find . -maxdepth 2. Avoid dir /s /b.
• •Step 2: Identify "Core Files" (entry points, main features).
• •Step 3: view_file at least 2-3 of these core files to gauge the "maturity" of the project.
• •Step 4: Skill Check: Briefly check .agent/skills and view_file any that seem relevant to the broad feature area (e.g. product-design, supabase).
• •Step 5: Acknowledge existing work specifically in your response (e.g., "I see you've already implemented X in file.tsx").
• •Step 6 (Sub-Agent Option): For very large codebases, spawn a "Cartographer" agent to map the project:
  • •claude -p "Generate a high-level architecture map of this project and save it to specs/project_map.md" --agent "scribe"

Refactoring Hygiene

• •Delete While Replacing: If you refactor a component to replace another (e.g., creating ProductDetailModal to replace PantryItemDetail), you MUST proactively identify and delete the obsolete file in the same coding session. Do not leave "zombie code" for a future cleanup pass.

Phase Discipline: Read-Only Planning

• •CRITICAL: During the /plan workflow or any "Discovery/Planning" phase, you are in READ-ONLY MODE.
• •Forbidden Actions: Do NOT use write_to_file, replace_file_content, or run_command (except for ls, cat, or read-only tools) on project code.
• •Exception: You may ONLY write to specs/issue_*.md, specs/active_PRD.md, or .agent files.
• •Why: Writing code before the plan is approved causes "rogue" behavior, wasted effort, and violates the "Measure Twice, Cut Once" principle.