Note: The current year is 2025. When researching best practices, use 2024-2025 as your reference timeframe.

1. Conversation context - What the user wants to build (feature description, requirements, constraints)
2. Continuity ledger (if exists) - Current session state
3. Handoff directory - Where to save your handoff (usually

   thoughts/handoffs/<session>/

   )
4. Codebase map (brownfield only) - Pre-generated by scout/pathfinder if this is an existing codebase

• Check for

  codebase-map.md

  in handoff directory
• If found: Use it as your primary codebase context (skip heavy exploration)
• The codebase-map contains structure, entry points, patterns

• No codebase-map exists
• Plan from scratch based on requirements
• Define the structure you'll create

1. Problem Definition
   • "What specific pain point does this solve?"
   • "What happens today without this feature?"
   • "Who encounters this problem and when?"
2. User Context
   • "Walk me through the user's workflow when they'd use this"
   • "What's the user's technical level?"
   • "Are there accessibility requirements?"
3. Technical Constraints
   • "What existing systems does this need to integrate with?"
   • "Are there performance requirements (latency, throughput)?"
   • "What's the data sensitivity level?"
4. Edge Cases & Error Handling
   • "What's the worst thing that could go wrong?"
   • "What happens if the user provides invalid input?"
   • "Are there rate limits or quotas to consider?"
5. Success Criteria
   • "How will you know this feature is successful?"
   • "What metrics would indicate failure?"
   • "What's the MVP vs nice-to-have?"
6. Tradeoffs
   • "If we had to cut scope, what's essential vs optional?"
   • "Speed vs thoroughness - where on the spectrum?"
   • "Build vs buy considerations?"

• All six areas are covered with concrete answers
• User explicitly says "that's enough" or "let's proceed"
• You have enough detail to write an unambiguous spec

thoughts/shared/plans/<feature>-spec.md

• Problem statement
• User stories with acceptance criteria
• Technical requirements
• Edge cases and error handling
• Success metrics
• Open questions (if any remain)

• What the user wants to build
• Why they need it (business context)
• Constraints mentioned (tech choices, patterns to follow)
• Any files or areas already discussed

• Files that will be modified
• Files with patterns to follow
• Test files for the area

• [Choice Category]: [Decision] - [Brief rationale]
• [Choice Category]: [Decision] - [Brief rationale]

• path/to/file.ts

  - [Role in the feature]

• path/to/other.ts

  - [Role in the feature]

• [Specific change 1]
• [Specific change 2]

• path/to/file.ts

• [Specific change 1]
• [Specific change 2]

• [Test command]:

  uv run pytest ...

• [Build command]:

  uv run ...

• [Type check]:

  ...

• [Manual test 1]
• [Manual test 2]

• [What we're NOT doing]
• [Future considerations]

undefined

1. [Task 1 name] - [Brief description]
2. [Task 2 name] - [Brief description]
3. [Task 3 name] - [Brief description] [...]

• [Key finding 1 with file:line reference]
• [Key finding 2]
• [Pattern to follow]

• [Assumption 1] - verify before implementation
• [Assumption 2]

• User should review plan at:

  thoughts/shared/plans/PLAN-<description>.md

• After approval, run

  /implement_plan

  with the plan path
• Research validation will occur before implementation

undefined

1. Mental checklist (ask yourself):
   • What's the single biggest thing that could go wrong?
   • Any external dependencies that could fail?
   • Is rollback possible if this breaks?
   • Edge cases not covered?
   • Unclear requirements that could cause rework?
2. If you identify HIGH severity risks:
   • Add a "## Risks" section to the plan
   • Note each TIGER (clear threat) with severity and mitigation
   • Note any ELEPHANTS (unspoken concerns)
3. Format for risks section (add to plan if risks found):
   markdown

   ## Risks (Pre-Mortem)
   
   ### Tigers:
   - **[Risk description]** (HIGH/MEDIUM)
     - Mitigation: [suggested approach]
   
   ### Elephants:
   - **[Unspoken concern]** (MEDIUM)
     - Note: [why this matters]

/premortem deep

• Research the codebase thoroughly before planning
• Read relevant files completely (no limit/offset)
• Follow existing patterns you discover
• Create specific, actionable tasks
• Include both automated and manual success criteria
• Create the handoff even if you have uncertainties

• Create vague or abstract plans
• Skip codebase research
• Make assumptions without noting them
• Over-scope the plan
• Skip the handoff document

• Note assumptions in the handoff
• Mark uncertain areas as "VERIFY BEFORE IMPLEMENTING"
• The research-validation step will catch issues before implementation

• Clear goal statement
• Technical choices with rationale
• Current state analysis with file references
• Specific, actionable tasks (not vague)
• Each task has checkboxes and file references
• Success criteria (automated AND manual)
• Out of scope section
• Handoff created with assumptions noted