learnship 2.0.10 → 2.1.0

package/learnship/references/planning-config.md

@@ -197,21 +197,107 @@ These options were added in v2.0.0 to support the new compounding, review, ship,
 | `ship.conventional_commits` | `true` | Use conventional commit format in `/ship` |
 | `ship.pr_template` | `true` | Auto-generate PR description in `/ship` |
 
-### Example config.json with v2 options
+</v2_config_options>
+
+<v21_config_options>
+
+## v2.1.0 Configuration Options
+
+New sections and fields added in v2.1.0 for security, parallelization control, gates, and safety.
+
+### Workflow Section (new fields)
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `workflow.security_enforcement` | `true` | Enable per-phase security verification via `/secure-phase` |
+| `workflow.discuss_mode` | `"discuss"` | Discussion mode for discuss-phase |
+| `workflow.tdd_mode` | `false` | Instruct planner to apply `type: tdd` to eligible tasks |
+
+### Parallelization Section (replaces flat boolean)
+
+The `parallelization` field is now an object. Legacy flat `"parallelization": true` is still honored for backward compatibility.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `parallelization.enabled` | `false` | Enable parallel subagent execution on supported platforms |
+| `parallelization.plan_level` | `true` | Parallelize at plan level (each plan gets its own agent) |
+| `parallelization.task_level` | `false` | Parallelize at task level within a plan (experimental) |
+| `parallelization.max_concurrent_agents` | `5` | Maximum number of concurrent subagents per wave |
+| `parallelization.min_plans_for_parallel` | `2` | Minimum plans in a wave before parallelization activates |
+
+**Why default 5?** Each subagent gets its own context window (~200k tokens). 5 agents is the sweet spot for cost vs. speed — most phases have 2-5 plans per wave. Going higher risks git lock contention and significant cost spikes without proportional speed gains. Configurable for power users.
+
+### Gates Section
+
+Controls which confirmation prompts are shown during workflows. Set to `false` to skip specific confirmations (useful for experienced users in yolo mode).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `gates.confirm_project` | `true` | Confirm PROJECT.md before proceeding |
+| `gates.confirm_phases` | `true` | Confirm phase breakdown |
+| `gates.confirm_roadmap` | `true` | Confirm roadmap before proceeding |
+| `gates.confirm_plan` | `true` | Confirm plans before execution |
+| `gates.execute_next_plan` | `true` | Confirm before executing each plan |
+| `gates.issues_review` | `true` | Confirm issue resolution approach |
+| `gates.confirm_transition` | `true` | Confirm before phase transitions |
+
+### Safety Section
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `safety.always_confirm_destructive` | `true` | Always confirm before destructive operations (file deletion, git reset) |
+| `safety.always_confirm_external_services` | `true` | Always confirm before calling external APIs or services |
+
+### Hooks Section
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `hooks.context_warnings` | `true` | Show context budget warnings when usage is high |
+
+### Example config.json with all v2.1 options
 
 ```json
 {
   "mode": "interactive",
+  "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
-  "parallelization": false,
   "test_first": false,
+  "planning": {
+    "commit_docs": true,
+    "commit_mode": "auto",
+    "search_gitignored": false
+  },
   "workflow": {
-    "review": true,
-    "solutions_search": true,
     "research": true,
     "plan_check": true,
-    "verifier": true
+    "verifier": true,
+    "validation": true,
+    "review": true,
+    "solutions_search": true,
+    "security_enforcement": true,
+    "discuss_mode": "discuss",
+    "tdd_mode": false
+  },
+  "parallelization": {
+    "enabled": false,
+    "plan_level": true,
+    "task_level": false,
+    "max_concurrent_agents": 5,
+    "min_plans_for_parallel": 2
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_phases": true,
+    "confirm_roadmap": true,
+    "confirm_plan": true,
+    "execute_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
   },
   "review": {
     "auto_after_verify": false
@@ -221,13 +307,17 @@ These options were added in v2.0.0 to support the new compounding, review, ship,
     "conventional_commits": true,
     "pr_template": true
   },
-  "planning": {
-    "commit_docs": true,
-    "search_gitignored": false
+  "hooks": {
+    "context_warnings": true
+  },
+  "git": {
+    "branching_strategy": "none",
+    "phase_branch_template": "phase-{phase}-{slug}",
+    "milestone_branch_template": "{milestone}-{slug}"
   }
 }
 ```
 
-</v2_config_options>
+</v21_config_options>
 
 </planning_config>

package/learnship/references/thinking-models.md

@@ -0,0 +1,61 @@
+<thinking_models>
+
+Structured reasoning models for the **planner** and **plan-checker** agents. Apply these at decision points during plan creation, not continuously. Each model counters a specific failure mode.
+
+## Conflict Resolution
+
+Pre-Mortem and Constraint Analysis both analyze risk at different granularities. Run Constraint Analysis FIRST (identify the hardest constraint), then Pre-Mortem (enumerate failure modes around that constraint and the rest of the plan).
+
+## 1. Pre-Mortem Analysis
+
+**Counters:** Optimistic plan decomposition that ignores failure modes.
+
+Before finalizing this plan, assume it has already failed. List the 3 most likely reasons for failure — missing dependency, wrong decomposition, underestimated complexity — and add mitigation steps or acceptance criteria that would catch each failure early.
+
+## 2. MECE Decomposition
+
+**Counters:** Overlapping tasks (merge conflicts) or gapped tasks (missing requirements).
+
+Verify this task breakdown is MECE at the REQUIREMENT level: (1) list every requirement from the phase goal, (2) confirm each maps to exactly one task's `<done>`, (3) if two tasks modify the same file, confirm they modify DIFFERENT sections or serve DIFFERENT requirements, (4) flag any requirement not covered by any task.
+
+## 3. Constraint Analysis
+
+**Counters:** Deferring the hardest constraint to the last task, causing late-stage failures.
+
+Identify the single hardest constraint in this phase — the one thing that, if it doesn't work, makes everything else irrelevant. Schedule that constraint as Task 1 or 2, not last. If the constraint involves an external API or unfamiliar library, add a spike/proof-of-concept task before the main implementation.
+
+## 4. Reversibility Test
+
+**Counters:** Over-analyzing cheap decisions, under-analyzing costly ones.
+
+For each significant decision in this plan, classify as REVERSIBLE (can change later with low cost) or IRREVERSIBLE (changing later requires migration, breaking changes, or significant rework). Spend analysis time proportional to irreversibility. For irreversible decisions, document the rationale in the plan.
+
+## 5. Curse of Knowledge Counter
+
+**Counters:** Plan-to-executor ambiguity from compressed instructions.
+
+For each `<action>` step, re-read it as if you have NEVER seen this codebase. Is every noun unambiguous (which file? which function? which endpoint?)? Is every verb specific (add WHERE? modify HOW?)? If a step could be interpreted two ways, rewrite it. Include file paths, function names, and expected behavior in every action step.
+
+## 6. Base Rate Neglect Counter
+
+**Counters:** Planners ignoring low-confidence research caveats.
+
+Before finalizing the plan, read ALL `[NEEDS DECISION]` items and LOW-confidence recommendations from RESEARCH.md. For each: either (a) create a checkpoint task to resolve it, or (b) document why the risk is acceptable in the plan's deviation notes. Low-confidence items that are silently accepted become undocumented technical debt.
+
+## Gap Closure Mode: Root-Cause Check
+
+**Applies only when:** Planner enters gap closure mode (triggered by `gaps_found` in VERIFICATION.md).
+
+Before writing the fix plan, apply a single "why" round: Why did this gap occur? Was it a plan deficiency (wrong task), an execution miss (correct task, wrong implementation), or a changed assumption (environment/dependency shift)? The fix plan must target the root cause category, not just the symptom.
+
+---
+
+## When NOT to Think
+
+Skip structured reasoning models when the situation does not benefit from them:
+
+- **Single-task plans** — If the phase has one clear requirement and one obvious task, do not run Pre-Mortem or MECE analysis. Write the task directly.
+- **Well-researched phases** — If RESEARCH.md has HIGH-confidence recommendations for every decision and no `[NEEDS DECISION]` items, skip Base Rate Neglect Counter.
+- **Gap closure plans** — Focus on the Root-Cause Check model only. Skip all others — the original plan already went through them.
+
+</thinking_models>

package/learnship/references/universal-anti-patterns.md

@@ -0,0 +1,51 @@
+<universal_anti_patterns>
+
+Rules that apply to ALL workflows and agents. Individual workflows may have additional specific anti-patterns.
+
+---
+
+## Context Budget Rules
+
+1. **Never** read agent definition files (`agents/*.md`) when spawning subagents — `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
+2. **Never** inline large files into subagent prompts — tell agents to read files from disk instead. Agents have their own context windows.
+3. **Read depth scales with context window** — check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000: full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+4. **Delegate** heavy work to subagents — the orchestrator routes, it does not build, analyze, research, investigate, or verify.
+5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## File Reading Rules
+
+6. **SUMMARY.md read depth scales with context window** — at context_window < 500000: read frontmatter only from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. Transitive dependencies (2+ phases back) remain frontmatter-only regardless.
+7. **Never** read full PLAN.md files from other phases — only current phase plans.
+8. **Do not** re-read full file contents when frontmatter is sufficient — frontmatter contains status, key_files, commits, and provides fields.
+
+## Subagent Rules
+
+9. **Always use learnship agent types** (`learnship-executor`, `learnship-planner`, `learnship-phase-researcher`, etc.) — never fall back to generic or built-in agent types. Learnship agents have project-aware prompts and workflow context.
+10. **Do not** re-litigate decisions that are already locked in CONTEXT.md — respect locked decisions unconditionally.
+
+## Questioning Anti-Patterns
+
+11. **Do not** walk through checklists — checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
+12. **Do not** use corporate speak — avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
+13. **Do not** apply premature constraints — don't narrow the solution space before understanding the problem. Ask about the problem first, then constrain.
+
+## State Management Anti-Patterns
+
+14. **Always use atomic file writes for STATE.md and ROADMAP.md.** Read the current content, modify, write the whole file. Do not use append-only operations that could corrupt the file on interruption.
+15. **Never** skip STATE.md updates after completing work — downstream workflows depend on accurate state.
+
+## Behavioral Rules
+
+16. **Do not** create artifacts the user did not approve — always confirm before writing new planning documents.
+17. **Do not** modify files outside the workflow's stated scope — check the plan's files_modified list.
+18. **Do not** suggest multiple next actions without clear priority — one primary suggestion, alternatives listed secondary.
+19. **Do not** use `git add .` or `git add -A` — stage specific files only.
+20. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules
+
+21. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically).
+22. **Config fallback awareness**: Config loading returns `null` silently on invalid JSON. If your workflow depends on config values, check for null and warn the user: "config.json is invalid or missing — running with defaults."
+23. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest diagnosing the mismatch.
+
+</universal_anti_patterns>

package/learnship/templates/agents.md

@@ -21,6 +21,9 @@ collaborators with different strengths.
   The "why" matters more than the "what."
 - **Domain-aware, not domain-faking.** Know the domain of this project. When uncertain about
   domain concepts, say so rather than hallucinate. Getting it wrong here has real consequences.
+- **Stop when confused, not after.** If something is ambiguous, surface it immediately. Present
+  the interpretations. Ask which one. Don't pick silently and run with it — that's how wrong
+  assumptions become wrong code.
 - **Learnings are first-class.** Every significant fix gets a "why it broke" and "what we
   learned." This is non-negotiable.
 - **Swearing is allowed when it lands.** Don't force it. Don't avoid it.
@@ -46,9 +49,13 @@ Decision-making heuristics for navigating ambiguity.
 When something is hard to implement, that's information about the design — not just an
 obstacle to power through. Investigate the resistance before routing around it.
 
-### 2. Minimal Upstream Fix Over Downstream Workaround
+### 2. Minimal Fix, Surgical Change
 
-Fix the root cause. Don't patch symptoms. One fix, one place.
+Fix the root cause, not the symptoms. One fix, one place. Touch only what you must — don't
+"improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken.
+Match existing style, even if you'd do it differently. Every changed line should trace directly
+to the request. When your changes create orphans (unused imports, dead variables), clean those
+up — but don't remove pre-existing dead code unless asked.
 
 ### 3. Preserve Real-World Signal
 
@@ -70,15 +77,19 @@ future guardrails.
 
 When we disagree, the motivation is wanting the project to succeed — not being right.
 
-### 7. One Moving Part at a Time
+### 7. One Thing at a Time, Nothing Extra
 
 When debugging or adding features, change one thing, verify, then move to the next.
-Multi-variable changes obscure what actually fixed the problem.
+Multi-variable changes obscure what actually fixed the problem. Write the minimum code
+that solves the stated problem — no speculative features, no abstractions for single-use
+cases, no "flexibility" that wasn't requested. If 200 lines could be 50, rewrite.
 
-### 8. Code Reads > Code Writes
+### 8. Understand First, Then Change
 
 Read existing code thoroughly before editing. Understand the current design before proposing
-changes. Most bugs come from not understanding what's already there. Read first, always.
+changes. Most bugs come from not understanding what's already there. When something is
+ambiguous and multiple interpretations exist, present them and ask — don't silently pick one.
+If you're confused, stop. Name what's unclear. Ask.
 
 ### 9. Keep Copies in Sync
 
@@ -141,9 +152,12 @@ This project uses **learnship**. Key facts:
 
 - All planning artifacts live in `.planning/` — read STATE.md and ROADMAP.md first when unsure where we are
 - The phase loop: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work` → `/review` → `/ship` → `/compound`
+- Optional per-phase: `/secure-phase` (security verification), `/extract-learnings` (capture meta-knowledge)
+- Recovery: `/forensics` (post-mortem), `/undo` (safe revert)
 - Current status is always in `.planning/STATE.md`
 - Decisions are tracked in `.planning/DECISIONS.md` — read it before proposing approaches that may conflict
 - Compounded solutions live in `.planning/solutions/` — organized by category with YAML frontmatter (module, problem_type, severity, tags). Search these before planning to avoid reinventing known solutions
+- Quick ideas: `/note [text]` for zero-friction capture, `/session-report` for end-of-session summaries
 - Run `/ls` if context is unclear about what phase we're on or what to do next — it shows status and offers to run the next step
 
 ---

package/learnship/templates/context.md

@@ -6,67 +6,242 @@ workflow: discuss-phase
 
 # Phase [N] Context: [Phase Name]
 
-Implementation decisions captured during `discuss-phase [N]`. This file is read by the planner, researcher, and executor — it represents locked user preferences that override default approaches.
+Implementation decisions captured during `discuss-phase [N]`. This file is the primary input for downstream agents — the researcher uses it to know WHAT to investigate, the planner uses it to know WHAT choices are locked.
 
----
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
 
+<decisions>
 ## Implementation Decisions
 
-### Technology Choices
+### [Area 1 that was discussed]
+- **D-01:** [Specific decision made]
+- **D-02:** [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- **D-03:** [Specific decision made]
+
+### [Area 3 that was discussed]
+- **D-04:** [Specific decision made]
+
+### Claude's Discretion
+[Areas where user explicitly said "you decide" — the agent has flexibility here during planning/implementation]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
 
-*What specific libraries, frameworks, or tools should be used?*
+[If none: "No specific requirements — open to standard approaches"]
 
-- [Decision]: [Choice] — [rationale]
-- [Decision]: [Choice] — [rationale]
+</specifics>
 
-### Architecture Preferences
+<canonical_refs>
+## Canonical References
 
-*How should this be structured? Patterns, layers, component organization?*
+**Downstream agents MUST read these before planning or implementing.**
 
-- [Decision]: [Choice] — [rationale]
+[List every spec, ADR, feature doc, or design doc that defines requirements or constraints for this phase. Use full relative paths so agents can read them directly.]
 
-### Scope Boundaries
+### [Topic area 1]
+- `path/to/spec-or-adr.md` — [What this doc decides/defines that's relevant]
 
-*What's explicitly in scope vs. explicitly deferred?*
+### [Topic area 2]
+- `path/to/feature-doc.md` — [What capability this defines]
 
-**In scope for this phase:**
-- [item]
-- [item]
+[If the project has no external specs: "No external specs — requirements are fully captured in decisions above"]
 
-**Explicitly deferred (do not implement):**
-- [item]
-- [item]
+</canonical_refs>
 
-### UI/UX Decisions
+<code_context>
+## Existing Code Insights
 
-*Visual style, interaction patterns, design direction (if UI work)*
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
 
-- [Decision]: [Choice] — [rationale]
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
 
 ### Integration Points
+- [Where new code connects to existing system]
 
-*How should this phase connect to other phases or existing systems?*
+</code_context>
 
-- [item]: [approach]
+<deferred>
+## Deferred Ideas
 
-### Quality Standards
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
 
-*Performance targets, error handling approach, test coverage expectations*
+[If none: "None — discussion stayed within phase scope"]
 
-- [item]: [requirement]
+</deferred>
 
 ---
 
-## Open Questions
+*Phase: [padded]-[slug]*
+*Context gathered: [date]*
 
-*Unresolved items — planner should make a reasonable default choice and note it*
+---
 
-- [question]: [status — TBD / will decide during planning / not critical]
+<good_examples>
 
----
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+</domain>
+
+<decisions>
+## Implementation Decisions
 
-## Anti-Patterns to Avoid
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
 
-*Approaches the user explicitly wants to avoid*
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+### Feed display
+- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
+
+### Empty states
+- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
+</canonical_refs>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+</deferred>
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+</domain>
+
+<decisions>
+## Implementation Decisions
 
-- [anti-pattern]: [reason]
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+### Backup CLI
+- `docs/features/backup-restore.md` — Backup requirements, supported backends, encryption spec
+- `docs/decisions/adr-007-cli-conventions.md` — Flag naming, exit codes, output format standards
+</canonical_refs>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+</deferred>
+```
+
+</good_examples>
+
+<guidelines>
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase_num}-CONTEXT.md`
+- The researcher uses decisions to focus investigation AND reads canonical_refs to know WHAT docs to study
+- The planner uses decisions + research to create executable tasks AND reads canonical_refs to verify alignment
+- Downstream agents should NOT need to ask the user again about captured decisions
+
+**Canonical references:**
+- The `<canonical_refs>` section is MANDATORY. Every CONTEXT.md must have one.
+- If your project has external specs, ADRs, or design docs, list them with full relative paths grouped by topic
+- If ROADMAP.md lists `Canonical refs:` per phase, extract and expand those
+- If no external specs exist, say so explicitly — don't silently omit the section
+</guidelines>

package/learnship/templates/discussion-log.md

@@ -0,0 +1,49 @@
+---
+phase: [N]
+slug: [phase-slug]
+areas_discussed: []
+created: [date]
+---
+
+# Phase [N]: [Name] - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** [ISO date]
+**Phase:** [phase number]-[phase name]
+**Areas discussed:** [comma-separated list]
+
+---
+
+## [Area 1 Name]
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| [Option 1] | [Brief description] | |
+| [Option 2] | [Brief description] | ✓ |
+| [Option 3] | [Brief description] | |
+
+**User's choice:** [Selected option or verbatim free-text response]
+**Notes:** [Any clarifications or rationale provided during discussion]
+
+---
+
+## [Area 2 Name]
+
+...
+
+---
+
+## Claude's Discretion
+
+[Areas delegated to Claude's judgment — list what was deferred and why]
+
+## Deferred Ideas
+
+[Ideas mentioned but not in scope for this phase]
+
+---
+
+*Phase: [padded]-[slug]*
+*Discussion log generated: [date]*