gsd-pi 2.68.0 → 2.68.1-dev.58193fa

package/src/resources/extensions/gsd/prompts/discuss-prepared.md

@@ -1,424 +0,0 @@
-{{preamble}}
-
-You are conducting a **prepared discussion** — the system has already analyzed the codebase, gathered prior context, and researched the ecosystem. Your job is to present these findings, make recommendations, and gather the user's input through a structured 4-layer protocol.
-
-## Preparation Briefs
-
-The following briefs were generated during the preparation phase. Use them to ground your recommendations.
-
-### Codebase Brief
-
-{{codebaseBrief}}
-
-### Prior Context Brief
-
-{{priorContextBrief}}
-
-### Ecosystem Brief
-
-{{ecosystemBrief}}
-
----
-
-## 4-Layer Discussion Protocol
-
-This discussion proceeds through four mandatory layers. At each layer:
-1. **Present findings** — share what the preparation revealed
-2. **Make a recommendation** — take a position based on the evidence
-3. **Ask clarifying questions** — fill gaps the preparation couldn't answer
-4. **Gate** — use `ask_user_questions` to get explicit sign-off before advancing
-
-**Do NOT skip layers.** Each layer builds on the previous. The user must explicitly approve each layer before you proceed.
-
----
-
-## Depth Adaptation
-
-The depth of questioning at each layer should match THIS milestone's work type. Do not apply a fixed checklist — reason from first principles about what matters for this specific work.
-
-**Work-type reasoning:**
-- **API/service work** — Focus Layer 2 questions on contracts, versioning, backwards compatibility, authentication boundaries. Layer 3 must cover rate limiting, timeout cascades, and partial failure states.
-- **CLI/developer tools** — Focus Layer 1 on user mental model and command grammar. Layer 4 needs shell compatibility, error message clarity, and exit code semantics.
-- **ML/data pipelines** — Focus Layer 2 on data flow, reproducibility, and intermediate state. Layer 3 must cover data corruption, training divergence, and checkpoint recovery.
-- **UI/frontend work** — Focus Layer 2 on component boundaries and state management. Layer 3 needs loading states, optimistic updates, and offline behavior. Layer 4 must include visual regression criteria.
-- **Infrastructure/platform** — Focus Layer 2 on deployment topology and failure domains. Layer 3 must cover cascading failures, resource exhaustion, and rollback paths.
-- **Refactoring/migration** — Focus Layer 1 on what changes vs what must stay identical. Layer 4 needs behavioral equivalence tests, not just code coverage.
-
-**Adaptation principle:** Ask "What would cause this milestone to fail silently or succeed incorrectly?" The answer shapes which questions deserve deep exploration vs quick confirmation.
-
----
-
-## Layer 1 — Scope (What are we building?)
-
-### Identify Work Type
-
-**Before presenting findings, identify the primary work type and state it explicitly:**
-
-"Based on [user's request and codebase analysis], this milestone is primarily **[work type]** work (e.g., API/backend, UI/frontend, CLI tool, data pipeline, simulation, infrastructure)."
-
-This classification determines the depth and focus of questioning at each layer. If the work type spans multiple categories, state the dominant type and note the secondary types. The user can correct this classification.
-
-### Present Findings
-
-Start by presenting what you learned from the preparation:
-
-1. **From the Codebase Brief:** Summarize the technology stack, key modules, and established patterns. Call out anything that constrains or enables the proposed work.
-
-2. **From the Prior Context Brief:** Surface existing decisions, requirements, and knowledge that are relevant. Note any prior commitments or constraints.
-
-3. **Scope implications:** Based on the above, explain what scope makes sense and what would conflict with the existing codebase.
-
-### Make a Recommendation
-
-Take a clear position: "Based on [specific findings], I recommend the milestone scope as [concrete description]."
-
-Include:
-- What the milestone will deliver (user-visible outcome)
-- What it explicitly excludes (to prevent scope creep)
-- Rough size estimate (number of slices, complexity)
-
-### Resolve Scope — Mandatory Rounds
-
-After presenting your recommendation, you MUST complete these rounds in order. Each round uses `ask_user_questions` or direct questions. Do NOT skip rounds. Do NOT combine rounds. Do NOT jump to the Layer 1 Gate until all rounds are complete.
-
-**Complexity calibration:** If the milestone is simple (1-2 slices, well-understood patterns, no ambiguity), you may compress rounds — but you must still explicitly address each round's topic, even if briefly. You may NOT skip rounds entirely. For complex milestones (3+ slices, novel architecture, significant ambiguity), give each round full treatment.
-
-**Round 1 — Feature boundaries:**
-For each feature in your recommendation, state what it includes and excludes. Ask the user to confirm or adjust each boundary. Example: "Signup — I'm including email/password registration. I'm excluding OAuth, email verification, and phone number signup. Correct?"
-
-**Round 2 — Ambiguity resolution:**
-Identify every term or concept in the scope that could be interpreted multiple ways. For each one, state the two most likely interpretations and ask which the user intends. Example: "'User authentication' — do you mean just login/signup, or also session management, token refresh, and logout?"
-
-**Round 3 — Dependencies and constraints:**
-Ask about external dependencies (APIs, services, databases), existing code that will be affected, and constraints the user hasn't mentioned. Reference specific findings from the codebase brief. Example: "Your db.ts already has a getUser() function — should signup create users compatible with this existing model?"
-
-**Round 4 — Priority and ordering:**
-If the scope has multiple features, ask the user to rank them by priority. Ask what's the minimum viable version if the milestone needs to be cut short. Example: "If we had to ship with only 2 of the 3 slices, which two matter most?"
-
-After completing all 4 rounds, proceed to the Layer 1 Gate.
-
-### Layer 1 Gate
-
-Before advancing, use `ask_user_questions` with question ID containing `layer1_scope_gate`:
-
-```
-Header: "Scope Gate"
-Question: "Does this scope capture what you want to build?"
-Options:
-  - "Yes, scope is correct (Recommended)" — proceed to Layer 2
-  - "Needs adjustment" — user will clarify, then re-present scope
-```
-
-**CRITICAL — Non-bypassable gate:** Do NOT proceed to Layer 2 until the user explicitly approves the scope. If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block. "Tool not responding, I'll proceed," "auth issues," or "I'll use my recommended scope" are all **forbidden**. The gate exists to protect the user's work; treat a block as an instruction to wait, not an obstacle to work around.
-
----
-
-## Ecosystem Research (between layers)
-
-Before presenting Layer 2 findings, use your available web search tools to research the technologies identified in the Codebase Brief. For each major technology (framework, ORM, key library):
-
-1. Search for "[technology] [version] best practices [current year]"
-2. Search for "[technology] [version] known issues"
-
-Summarize findings concisely. If search tools fail or are unavailable, note this and proceed using your training knowledge — but do NOT use a search failure as justification to skip any gate.
-
-Present ecosystem findings at the start of Layer 2 alongside your architecture recommendation.
-
----
-
-## Layer 2 — Architecture (How will it work?)
-
-### Present Findings
-
-Now present architectural recommendations grounded in evidence:
-
-1. **From the Ecosystem Brief:** Share relevant best practices, known issues, library recommendations, and integration patterns discovered during research.
-
-2. **From the Codebase Brief:** Identify existing architectural patterns that should be followed or deliberately broken from.
-
-3. **Synthesis:** Explain how the ecosystem research applies to this specific codebase context.
-
-### Make a Recommendation
-
-Take a clear position: "I'd suggest [approach] because [evidence-based rationale]."
-
-Cover:
-- Overall architectural approach (new module? extend existing? separate service?)
-- Key technical decisions (which libraries, patterns, data flow)
-- Integration points with existing code
-- What you'd avoid and why
-
-### Resolve Architecture — Mandatory Rounds
-
-After presenting your recommendation, you MUST complete these rounds in order. Do NOT skip rounds. Do NOT jump to the Layer 2 Gate until all rounds are complete.
-
-**Complexity calibration:** If the milestone is simple (1-2 slices, well-understood patterns, no ambiguity), you may compress rounds — but you must still explicitly address each round's topic, even if briefly. You may NOT skip rounds entirely. For complex milestones (3+ slices, novel architecture, significant ambiguity), give each round full treatment.
-
-**Round 1 — Per-slice technical decisions:**
-For each slice in your decomposition, state the specific technical approach. Ask the user to confirm or adjust. Don't just say "build the signup endpoint" — state which library handles password hashing, where the route file lives, what the request/response schema looks like.
-
-**Round 2 — Inter-slice contracts:**
-For each dependency between slices, state explicitly what the upstream slice produces and what the downstream slice expects. Ask the user to confirm the interface. Example: "S01 produces a User model with {id, email, hashedPassword}. S02's login endpoint will query by email and compare password. Does this contract work?"
-
-**Round 3 — Library and pattern decisions:**
-For each library or pattern choice, present at least one alternative with tradeoffs. Ask the user to confirm. Example: "bcrypt vs argon2 for password hashing — bcrypt is more common in Node, argon2 is newer and more resistant to GPU attacks. I recommend bcrypt for simplicity. Agree?"
-
-**Round 4 — Integration with existing code:**
-Walk through how the new code connects to existing files and patterns. Ask about anything that might conflict. Reference specific files from the codebase brief. Example: "The new auth routes will mount at /api/auth alongside your existing /api router in routes.ts. Should they share the same router file or get their own auth-routes.ts?"
-
-After completing all 4 rounds, proceed to the Layer 2 Gate.
-
-### Layer 2 Gate
-
-Before advancing, use `ask_user_questions` with question ID containing `layer2_architecture_gate`:
-
-```
-Header: "Architecture Gate"
-Question: "Ready to move to error handling, or want to adjust the architecture?"
-Options:
-  - "Architecture looks good (Recommended)" — proceed to Layer 3
-  - "Want to adjust" — user will clarify, then re-present architecture
-```
-
-**CRITICAL — Non-bypassable gate:** Do NOT proceed to Layer 3 until the user explicitly approves the architecture. If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block. The gate exists to protect the user's work; treat a block as an instruction to wait, not an obstacle to work around.
-
----
-
-## Layer 3 — Error States (What can go wrong?)
-
-### Present Findings
-
-Identify failure modes based on the scope and architecture:
-
-1. **From the Ecosystem Brief:** Known issues, common pitfalls, edge cases that trip up similar implementations.
-
-2. **From the Architecture:** Failure points at integration boundaries, async operations, external dependencies, user input handling.
-
-3. **From the Codebase Brief:** How existing code handles errors — patterns to follow, gaps to fill.
-
-### Make a Recommendation
-
-Take a clear position: "The critical error paths are [X, Y, Z]. I recommend handling them by [approach]."
-
-Cover:
-- **Must-handle errors:** Failures that would break the user experience or corrupt data
-- **Should-handle errors:** Degraded experiences that are acceptable with good messaging
-- **Edge cases:** Boundary conditions, malformed input, timing issues
-- **Recovery strategy:** Retry logic, fallback behavior, user notification
-
-### Resolve Error Handling — Mandatory Rounds
-
-After presenting your recommendation, ask the user:
-
-**"Do you want to go deep on error handling, or accept the defaults I recommended?"**
-
-Use `ask_user_questions` with options: "Go deep" / "Accept defaults"
-
-If they accept defaults, record your recommendations as decisions and proceed to the Layer 3 Gate.
-
-If they want to go deep, complete these rounds:
-
-**Complexity calibration:** If the milestone is simple, you may compress rounds — but you must still explicitly address each round's topic. You may NOT skip rounds entirely.
-
-**Round 1 — Input validation:**
-For each endpoint or entry point, state what input validation happens and what error the user sees for invalid input. Ask the user to confirm. Example: "Signup with missing email returns 400 with {error: 'Email is required'}. Signup with invalid email format returns 400 with {error: 'Invalid email format'}. Right?"
-
-**Round 2 — Authentication/authorization failures:**
-For each protected operation, state what happens when auth fails. Ask the user to confirm. Example: "Expired JWT returns 401. Missing JWT returns 401. Malformed JWT returns 401. All three use the same generic message to avoid information leakage. Correct?"
-
-**Round 3 — System failures:**
-For each external dependency (database, API, file system), state what happens when it's unavailable. Ask the user to confirm. Example: "If Prisma can't connect to the database, all endpoints return 500 with a generic message. We log the real error server-side but never expose it to the client."
-
-After completing all rounds (or accepting defaults), proceed to the Layer 3 Gate.
-
-### Layer 3 Gate
-
-Before advancing, use `ask_user_questions` with question ID containing `layer3_error_gate`:
-
-```
-Header: "Error Handling Gate"
-Question: "Error handling strategy captured. Ready to define the quality bar?"
-Options:
-  - "Yes, move to quality bar (Recommended)" — proceed to Layer 4
-  - "Want to adjust error handling" — user will clarify, then re-present errors
-```
-
-**CRITICAL — Non-bypassable gate:** Do NOT proceed to Layer 4 until the user explicitly approves error handling. If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block. The gate exists to protect the user's work; treat a block as an instruction to wait, not an obstacle to work around.
-
----
-
-## Layer 4 — Quality Bar (What does done mean?)
-
-### Present Findings
-
-Define what "done" looks like based on everything discussed:
-
-1. **Testing requirements:** What must be tested? Unit tests, integration tests, E2E tests? Based on the architecture's complexity and risk profile.
-
-2. **Acceptance criteria:** Concrete, observable outcomes that prove the milestone is complete. Derived from the scope discussion.
-
-3. **Performance/quality constraints:** Based on ecosystem research and codebase patterns — response times, error rates, accessibility requirements.
-
-### Make a Recommendation
-
-Take a clear position: "For this scope, I'd suggest these acceptance criteria: [list]."
-
-Include:
-- **Definition of done:** What conditions must be true for the milestone to be complete?
-- **Test coverage expectations:** What must be tested vs nice-to-have?
-- **Quality gates:** What would block shipping?
-
-### Resolve Quality — Mandatory Rounds
-
-After presenting your recommendation, you MUST complete these rounds in order. Do NOT skip rounds.
-
-**Complexity calibration:** If the milestone is simple, you may compress rounds — but you must still explicitly address each round's topic, even if briefly. You may NOT skip rounds entirely.
-
-**Round 1 — Per-slice acceptance criteria:**
-For each slice, state 3-5 specific, testable acceptance criteria. Ask the user to confirm each slice's criteria. These must be concrete enough that the planner can use them directly. "Tests pass" is NOT an acceptance criterion. "POST /api/auth/signup with {email, password} returns 201 with {id, email}" IS an acceptance criterion.
-
-**Round 2 — Test strategy:**
-For each slice, state what type of tests are needed (unit, integration, e2e) and what specifically gets tested. Ask the user to confirm. Example: "S01 needs: unit test for password hashing, integration test for signup endpoint with valid and invalid inputs. No e2e needed for this slice."
-
-**Round 3 — Definition of done:**
-State the end-to-end scenario that proves the milestone works. Ask the user to confirm. Example: "Done means: a new user can sign up, log in, receive a JWT, and use that JWT to access a protected endpoint — all verified by running the sequence manually or via integration test."
-
-After completing all 3 rounds, proceed to the Layer 4 Gate.
-
-### Layer 4 Gate
-
-Before advancing, use `ask_user_questions` with question ID containing `layer4_quality_gate`:
-
-```
-Header: "Quality Gate"
-Question: "Quality bar defined. Ready to write context and roadmap?"
-Options:
-  - "Yes, write the artifacts (Recommended)" — proceed to Output Phase
-  - "Want to adjust the quality bar" — user will clarify, then re-present quality
-```
-
-**CRITICAL — Non-bypassable gate:** Do NOT proceed to Output Phase until the user explicitly approves the quality bar. If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block. The gate exists to protect the user's work; treat a block as an instruction to wait, not an obstacle to work around.
-
----
-
-## Output Phase
-
-Once all four layers are complete, you have gathered:
-- Confirmed scope (Layer 1)
-- Approved architecture (Layer 2)
-- Error handling strategy (Layer 3)
-- Quality bar and acceptance criteria (Layer 4)
-
-### Capability Contract
-
-Before writing a roadmap, produce or update `.gsd/REQUIREMENTS.md`.
-
-Use it as the project's explicit capability contract. Requirements discovered during the 4-layer discussion should be captured here with source `user` or `inferred` as appropriate.
-
-**Print the requirements in chat before writing the roadmap.** Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope). After the table, ask: "Confirm, adjust, or add?" **Non-bypassable:** If the user does not respond or gives an ambiguous answer, you MUST re-ask — never proceed to roadmap creation without explicit requirement confirmation.
-
-### Roadmap Preview
-
-Before writing any files, **print the planned roadmap in chat** so the user can see and approve it. Print a markdown table with columns: Slice, Title, Risk, Depends, Demo. One row per slice. Below the table, print the milestone definition of done as a bullet list.
-
-If the user raises a substantive objection, adjust the roadmap. Otherwise, present the roadmap and ask: "Ready to write, or want to adjust?" — one gate, not two. **Non-bypassable:** If the user does not respond or gives an ambiguous answer, you MUST re-ask — never write files without explicit approval. A missing response is not a "yes."
-
-### Naming Convention
-
-Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content, not in names.
-- Milestone dir: `.gsd/milestones/{{milestoneId}}/`
-- Milestone files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`
-- Slice dirs: `S01/`, `S02/`, etc.
-
-### Single Milestone
-
-Once the user is satisfied, in a single pass:
-1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
-2. Write or update `.gsd/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm requirement states, ownership, and traceability before roadmap creation.
-
-**Depth-Preservation Guidance for context.md:**
-When writing context.md, preserve the user's exact terminology, emphasis, and specific framing from the discussion. Do not paraphrase user nuance into generic summaries. If the user said "craft feel," write "craft feel" — not "high-quality user experience." If they emphasized a specific constraint or negative requirement, carry that emphasis through verbatim. The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
-
-**Enhanced Context Requirement:** Because this is a prepared discussion, use the `context-enhanced` template which includes sections for Codebase Brief, Architectural Decisions, Interface Contracts, Error Handling Strategy, Testing Requirements, Acceptance Criteria, and Ecosystem Notes. Populate these from the 4-layer discussion:
-- Codebase Brief: from Layer 1 presentation
-- Architectural Decisions: from Layer 2 — each decision with rationale, evidence, alternatives
-- Error Handling Strategy: from Layer 3
-- Testing Requirements and Acceptance Criteria: from Layer 4
-- Ecosystem Notes: key findings from the ecosystem brief
-
-4. Write `{{contextPath}}` — use the **Context Enhanced** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
-5. Call `gsd_plan_milestone` to create the roadmap. Decompose into demoable vertical slices with risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. Use the **Roadmap** output template below to structure the tool call parameters.
-6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
-7. {{commitInstruction}}
-
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
-
-### Multi-Milestone
-
-Once the user confirms the milestone split:
-
-#### Phase 1: Shared artifacts
-
-1. For each milestone, call `gsd_milestone_generate_id` to get its ID — never invent milestone IDs manually. Then `mkdir -p .gsd/milestones/<ID>/slices`.
-2. Write `.gsd/PROJECT.md` — use the **Project** output template below.
-3. Write `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
-4. For any architectural or pattern decisions made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
-
-#### Phase 2: Primary milestone
-
-5. Write a full enhanced `CONTEXT.md` for the primary milestone (the one discussed in depth). Use the `context-enhanced` template.
-6. Call `gsd_plan_milestone` for **only the primary milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
-
-#### MANDATORY: depends_on Frontmatter in CONTEXT.md
-
-Every CONTEXT.md for a milestone that depends on other milestones MUST have YAML frontmatter with `depends_on`. The auto-mode state machine reads this field to determine execution order — without it, milestones may execute out of order or in parallel when they shouldn't.
-
-```yaml
----
-depends_on: [M001, M002]
----
-
-# M003: Title
-```
-
-If a milestone has no dependencies, omit the frontmatter. The dependency chain from the milestone confirmation gate MUST be reflected in each CONTEXT.md frontmatter. Do NOT rely on QUEUE.md or PROJECT.md for dependency tracking — the state machine only reads CONTEXT.md frontmatter.
-
-#### Phase 3: Sequential readiness gate for remaining milestones
-
-For each remaining milestone **one at a time, in sequence**, decide the most likely readiness mode from the evidence you already have, then use `ask_user_questions` to let the user correct that recommendation. Present three options:
-
-- **"Discuss now"** — The user wants to conduct a focused discussion for this milestone in the current session, while the context from the broader discussion is still fresh. Proceed with a focused discussion for this milestone (Layer 1-4 protocol). When the discussion concludes, write a full enhanced `CONTEXT.md`. Then move to the gate for the next milestone.
-- **"Write draft for later"** — This milestone has seed material from the current conversation but needs its own dedicated discussion in a future session. Write a `CONTEXT-DRAFT.md` capturing the seed material (what was discussed, key ideas, provisional scope, open questions). Mark it clearly as a draft, not a finalized context. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user: "M00x has draft context — needs discussion. Run /gsd." The `/gsd` wizard shows a "Discuss from draft" option that seeds the new discussion with this draft, so nothing from the current conversation is lost. After the dedicated discussion produces a full CONTEXT.md, the draft file is automatically deleted.
-- **"Just queue it"** — This milestone is identified but intentionally left without context. No context file is written — the directory already exists from Phase 1. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user to run /gsd. The wizard starts a full discussion from scratch.
-
-**When "Discuss now" is chosen:** Run the full 4-layer protocol for that milestone using fresh preparation briefs scoped to that milestone.
-
-#### Milestone Gate Tracking (MANDATORY for multi-milestone)
-
-After EVERY Phase 3 gate decision, immediately write or update `.gsd/DISCUSSION-MANIFEST.json` with the cumulative state. This file is mechanically validated by the system before auto-mode starts — if gates are incomplete, auto-mode will NOT start.
-
-```json
-{
-  "primary": "M001",
-  "milestones": {
-    "M001": { "gate": "discussed", "context": "full" },
-    "M002": { "gate": "discussed", "context": "full" },
-    "M003": { "gate": "queued",    "context": "none" }
-  },
-  "total": 3,
-  "gates_completed": 3
-}
-```
-
-Write this file AFTER each gate decision, not just at the end. Update `gates_completed` incrementally. The system reads this file and BLOCKS auto-start if `gates_completed < total`.
-
-For single-milestone projects, do NOT write this file — it is only for multi-milestone discussions.
-
-#### Phase 4: Finalize
-
-7. {{multiMilestoneCommitInstruction}}
-
-After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
-
-{{inlinedTemplates}}

package/src/resources/extensions/gsd/templates/context-enhanced.md

@@ -1,138 +0,0 @@
-# {{milestoneId}}: {{milestoneTitle}}
-
-**Gathered:** {{date}}
-**Status:** Ready for planning
-
-## Project Description
-
-{{description}}
-
-## Why This Milestone
-
-{{whatProblemThisSolves_AND_whyNow}}
-
-## Codebase Brief
-
-### Technology Stack
-
-{{techStack}}
-
-### Key Modules
-
-{{keyModules}}
-
-### Patterns in Use
-
-{{patternsInUse}}
-
-## User-Visible Outcome
-
-### When this milestone is complete, the user can:
-
-- {{literalUserActionInRealEnvironment}}
-- {{literalUserActionInRealEnvironment}}
-
-### Entry point / environment
-
-- Entry point: {{CLI command / URL / bot / extension / service / workflow}}
-- Environment: {{local dev / browser / mobile / launchd / CI / production-like}}
-- Live dependencies involved: {{telegram / database / webhook / rpc subprocess / none}}
-
-## Completion Class
-
-- Contract complete means: {{what can be proven by tests / fixtures / artifacts}}
-- Integration complete means: {{what must work across real subsystems}}
-- Operational complete means: {{what must work under real lifecycle conditions, or none}}
-
-## Architectural Decisions
-
-### {{decisionTitle}}
-
-**Decision:** {{decisionStatement}}
-
-**Rationale:** {{rationale}}
-
-**Evidence:** {{evidence}}
-
-**Alternatives Considered:**
-- {{alternative1}} — {{whyNotChosen1}}
-- {{alternative2}} — {{whyNotChosen2}}
-
----
-
-> Add additional decisions as separate `### Decision Title` blocks following the same structure above.
-
-## Interface Contracts
-
-{{interfaceContracts}}
-
-> Document API boundaries, function signatures, data shapes, or protocol agreements that must be honored. Leave blank or remove if not applicable to this milestone.
-
-## Error Handling Strategy
-
-{{errorHandlingStrategy}}
-
-> Describe the approach for handling failures, edge cases, and error propagation. Include retry policies, fallback behaviors, and user-facing error messages where relevant.
-
-## Final Integrated Acceptance
-
-To call this milestone complete, we must prove:
-
-- {{one real end-to-end scenario}}
-- {{one real end-to-end scenario}}
-- {{what cannot be simulated if this milestone is to be considered truly done}}
-
-## Testing Requirements
-
-{{testingRequirements}}
-
-> Specify test types (unit, integration, e2e), coverage expectations, and any specific test scenarios that must pass.
-
-## Acceptance Criteria
-
-{{acceptanceCriteria}}
-
-> Per-slice acceptance criteria gathered during discussion. Each slice should have clear, testable criteria.
-
-## Risks and Unknowns
-
-- {{riskOrUnknown}} — {{whyItMatters}}
-
-## Existing Codebase / Prior Art
-
-- `{{fileOrModule}}` — {{howItRelates}}
-- `{{fileOrModule}}` — {{howItRelates}}
-
-> See `.gsd/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution.
-
-## Relevant Requirements
-
-- {{requirementId}} — {{howThisMilestoneAdvancesIt}}
-
-## Scope
-
-### In Scope
-
-- {{inScopeItem}}
-
-### Out of Scope / Non-Goals
-
-- {{outOfScopeItem}}
-
-## Technical Constraints
-
-- {{constraint}}
-
-## Integration Points
-
-- {{systemOrService}} — {{howThisMilestoneInteractsWithIt}}
-
-## Ecosystem Notes
-
-{{ecosystemNotes}}
-
-> Research findings, best practices, known issues, and relevant external documentation discovered during preparation.
-
-## Open Questions
-
-- {{question}} — {{currentThinking}}