narrative-doc

name	narrative-doc
description	Write a narrative design or proposal document iteratively, section by section, with human sign-off at each step. Use when the user wants to write a proposal, narrative, or design rationale — not a formal requirements doc or low-level design spec.
argument-hint	Integration testing against Alpha before Beta deployment

Create a structured narrative/proposal document through an iterative, conversational process. Each section is drafted, reviewed by the human, and revised until approved before moving on. Terminology is maintained as a living table throughout. Mermaid diagrams are added where they improve clarity. Optionally stress-tested via a grill pass at the end.

Input

The user provides a topic description after the slash command, e.g.:

• /narrative-doc Integration testing against Alpha before Beta deployment
• /narrative-doc Migrating from REST to gRPC for internal service communication

The user may also reference prior research, decision briefs, or other context in conversation. If so, read those files to inform the document.

Process

Phase 1: Setup

1. Gather context. If the user has referenced research files, decision briefs, or other source material, read them. If the topic implies existing codebase context (e.g., current CI/CD setup, existing infrastructure), explore the relevant parts of the codebase to ground the document in reality.

2. Determine output location. Default to docs/ in the project root. If docs/ doesn't exist, create it. If the project has an alternative documentation directory (e.g., documentation/, design/), ask the user which to use.

3. Choose a filename. Derive a kebab-case filename from the topic, e.g., integration-tests-alpha-gate.md. Confirm with the user if ambiguous.

4. Create the document with the title and all section headers as placeholders:

# {Title}

## Background

## Terminology

| Term | Definition |
|------|------------|

## Goals

## Proposal

## Open Questions

## Appendices

Do not fill in any section content yet. The document structure is the starting point.

Phase 2: Background

1. Draft the Background section based on gathered context. The Background should explain the current state of things — how things work today, what the relevant systems/processes are, and what gap or problem motivates this document. Use subsections (### headings) to organize distinct aspects.

2. Add Mermaid diagrams wherever a visual would clarify a flow, architecture, or before/after comparison. Prefer flowcharts for processes and sequences.

3. Identify non-trivial terms used in the Background and add them to the Terminology table. A term is non-trivial if someone outside the immediate team might not know it, or if it has a project-specific meaning. If unsure about a term's definition, ask the user.

4. Present the Background to the user and wait for feedback. Iterate until the user signs off. Do not move to the next section until approved.

Phase 3: Goals

1. Draft the Goals section as a numbered list. Infer goals from the Background and any prior conversation. Each goal should have a bold one-line statement followed by a sentence or two of explanation.

2. Focus on what success looks like, not how to get there — that's the Proposal's job. Goals should be evaluable: a reader should be able to look at the finished work and say whether each goal was met.

3. Update Terminology if new terms appear.

4. Present to the user. Iterate until sign-off. Goals often get items added, removed, or reclassified as open questions during review — this is expected.

Phase 4: Proposal

1. Draft the Proposal section. Structure it with an Overview subsection (summarizing the approach at a high level with a Mermaid diagram) followed by detailed subsections for each major component of the proposal.

2. Be concrete. Reference specific systems, files, configurations, and patterns from the codebase where relevant. If a claim about the current state can be verified by reading code, verify it. Call out where the proposal requires changes to existing infrastructure, workflows, or code.

3. Acknowledge known gaps and asymmetries rather than glossing over them. If parts of the proposal require prototyping or have uncertain feasibility, say so explicitly and reference the Open Questions section.

4. Add Mermaid diagrams for deployment flows, architecture changes, before/after comparisons, and component relationships.

5. Update Terminology with any new terms introduced by the proposal.

6. Present to the user. The Proposal is typically the most iterative section — expect multiple rounds of revision. The user may restructure, add parts, or redirect the approach. Iterate until sign-off.

Phase 5: Open Questions

1. Seed the Open Questions section with questions that surfaced during Background, Goals, and Proposal drafting — items that were deferred, flagged as needing decisions, or identified as ambiguous.

2. Each question should be self-contained: a reader should understand what's being asked and why it matters without reading the rest of the document. Include enough context in each question to make it discussable in isolation.

3. Present to the user. The user may answer some questions on the spot (move those answers into the Proposal or Background as appropriate), add new questions, or reclassify proposal content as open questions. Iterate until sign-off.

Phase 6: Appendices

1. At minimum, include an Alternatives Considered appendix that describes approaches that were evaluated and not chosen, with pros/cons for each. If alternatives were discussed during the Proposal phase, collect them here.

2. Add additional appendices for detailed reference material that supports the Proposal but would interrupt its flow — e.g., per-component readiness assessments, implementation sketches, comparison matrices, or data from codebase exploration.

3. Present to the user. Iterate until sign-off.

Phase 7: Final Review & Optional Grill

1. Offer a grill pass:

   The document is drafted. Would you like me to grill you on it — stress-test the proposal for weak arguments, gaps, and missing considerations? I'll go through each concern one by one, suggesting changes as we go.

2. If the user accepts, conduct the grill:

   • Re-read the full document.
   • Explore the codebase to verify claims made in the document against actual code, configurations, and workflows.
   • Identify weak arguments, unstated assumptions, missing edge cases, and internal inconsistencies.
   • Present one concern at a time, with a specific question and your recommended answer. Wait for the user's response before moving on.
   • Update the document based on each answer — adding to the Proposal, Open Questions, Appendices, or Terminology as appropriate.
   • Continue until all substantive concerns are addressed.

3. If the user declines, do a final consistency check:

   • Verify section numbering is correct and sequential.
   • Verify all terms used in the document are defined in Terminology.
   • Verify the Overview's summary matches the detailed Proposal content.
   • Fix any inconsistencies silently and present a summary of what was cleaned up.

Output

A complete narrative document at docs/{filename}.md (or the user's chosen location) with:

• Background — current state and the gap being addressed
• Terminology — living table of all non-trivial terms, maintained throughout
• Goals — numbered, evaluable success criteria
• Proposal — detailed approach with Mermaid diagrams
• Open Questions — unresolved decisions with context
• Appendices — at minimum alternatives considered, plus any supporting reference material

The document is ready for sharing with stakeholders or using as a basis for implementation planning.