@drafthq/draft 2.7.0

package/skills/GRAPH.md

@@ -0,0 +1,332 @@
+# Skill Dependency Graph
+
+> Reference artifact mapping relationships between all Draft skills. Not a skill itself.
+> Regenerate after adding/removing skills or changing cross-skill references.
+
+---
+
+## Two-Tier Architecture
+
+### Primary Workflow (4 commands)
+```
+init → new-track → implement → review
+                       ↑           |
+                       └───────────┘  (auto-invoked at phase boundaries)
+```
+
+### Routed Core Workflows (5 routers)
+The 5 routers (`/draft:plan`, `/draft:ops`, `/draft:docs`, `/draft:discover`, `/draft:jira`) provide intent analysis and dispatch to the leaf specialist skills. Primary commands and routers are the public surface; leaves remain for compatibility and direct scripting.
+
+### Specialist Leaf Commands
+Grouped into subsystems dispatched by the routers (or primary commands).
+
+---
+
+## System Topology
+
+```mermaid
+graph TD
+    subgraph "Foundation"
+        init["/draft:init"]
+    end
+
+    subgraph "Track Lifecycle"
+        new-track["/draft:new-track"]
+        implement["/draft:implement"]
+        change["/draft:change"]
+        revert["/draft:revert"]
+        status["/draft:status"]
+    end
+
+    subgraph "Code Quality"
+        quick-review["/draft:quick-review"]
+        review["/draft:review"]
+        deep-review["/draft:deep-review"]
+        bughunt["/draft:bughunt"]
+        coverage["/draft:coverage"]
+        testing-strategy["/draft:testing-strategy"]
+        learn["/draft:learn"]
+    end
+
+    subgraph "Debugging"
+        debug["/draft:debug"]
+    end
+
+    subgraph "Architecture"
+        decompose["/draft:decompose"]
+        adr["/draft:adr"]
+        index["/draft:index"]
+        tech-debt["/draft:tech-debt"]
+        impact["/draft:impact"]
+    end
+
+    subgraph "Operations"
+        deploy-checklist["/draft:deploy-checklist"]
+        incident-response["/draft:incident-response"]
+        standup["/draft:standup"]
+    end
+
+    subgraph "Authoring"
+        documentation["/draft:documentation"]
+    end
+
+    subgraph "Integration"
+        jira["/draft:jira"]
+    end
+
+    subgraph "DX"
+        assist-review["/draft:assist-review"]
+        tour["/draft:tour"]
+    end
+
+    subgraph "Navigation"
+        draft["/draft"]
+    end
+
+    subgraph "Routed Core Workflows"
+        plan["/draft:plan"]
+        ops["/draft:ops"]
+        docs["/draft:docs"]
+        discover["/draft:discover"]
+        jira["/draft:jira"]
+    end
+
+    %% Foundation dependencies
+    init --> new-track
+    init --> learn
+    init --> adr
+    init --> bughunt
+    init --> index
+    init --> status
+    init --> deep-review
+    init --> debug
+    init --> tech-debt
+    init --> incident-response
+    init --> documentation
+    init --> standup
+
+    %% Router dispatch (primary entry for specialists)
+    plan --> new-track
+    plan --> decompose
+    plan --> adr
+    plan --> "tech-debt"
+    plan --> change
+    ops --> deploy-checklist
+    ops --> incident-response
+    ops --> standup
+    ops --> status
+    ops --> revert
+    docs --> documentation
+    discover --> debug
+    discover --> bughunt
+    discover --> quick-review
+    discover --> deep-review
+    discover --> coverage
+    discover --> testing-strategy
+    discover --> learn
+    discover --> index
+    discover --> tour
+    discover --> impact
+    discover --> assist-review
+    %% jira router handles preview/create/review internally
+
+    %% Track lifecycle
+    new-track --> implement
+    new-track --> change
+    new-track --> revert
+    new-track --> review
+    new-track --> coverage
+    new-track --> decompose
+    new-track --> jira  %% via router
+    new-track --> status
+    new-track --> debug
+
+    %% Implementation flow
+    implement -.->|auto-invokes at phase boundary| review
+    implement --> debug
+    implement -.->|calls Condensation Subroutine| init
+
+    %% Quality chain
+    review -.->|with-bughunt flag| bughunt
+    review -.->|fast alternative| quick-review
+    coverage -.->|calls Condensation Subroutine| init
+    testing-strategy -.->|informs| coverage
+    testing-strategy -.->|informs| bughunt
+
+    %% Cross-skill dispatch (quality → specialists)
+    bughunt -.->|suggests| debug
+    deep-review -.->|suggests| tech-debt
+    deep-review -.->|suggests| adr
+    deep-review -.->|suggests| documentation
+
+    %% Integration chain
+    %% preview/create/review are now subcommands of the jira router
+    bughunt -.->|report feeds| jira
+    review -.->|report feeds| jira
+
+    %% Operations chain
+    incident-response -.->|post-incident| debug
+    incident-response -.->|timeline feeds| documentation
+    standup -.->|reads| status
+    deploy-checklist -.->|reads| testing-strategy
+
+    %% Authoring chain
+    documentation -.->|reads| deep-review
+
+    %% Architecture chain
+    tech-debt -.->|prioritized items feed| new-track
+    impact -.->|reads graph| new-track
+    impact -.->|reads graph| implement
+
+    %% Monorepo chain
+    init -.->|per-service| index
+```
+
+## Dependency Matrix
+
+> Routers (`plan`, `ops`, `docs`, `discover`, `jira`) depend on their dispatched leaves and are the recommended public interface. Leaves list their direct deps.
+
+| Skill | Requires | Required By | Shared Artifacts |
+|-------|----------|-------------|-----------------|
+| `init` | -- | all others | architecture.md, .ai-context.md, .ai-profile.md, product.md, tech-stack.md, guardrails.md, .state/* |
+| `new-track` | init | implement, review, change, revert, coverage, decompose, jira, status, debug | spec.md, plan.md, metadata.json |
+| `implement` | init, new-track | review (triggers at phase boundaries) | Modifies source code; regenerates .ai-context.md |
+| `review` | init, new-track | implement (called at phase boundaries) | review-report-latest.md |
+| `quick-review` | init | review (fast alternative) | quick-review-report.md |
+| `bughunt` | init | review (optional), index (optional), jira (optional) | bughunt-report-latest.md |
+| `deep-review` | init | -- | deep-review audit report |
+| `coverage` | init, new-track | -- | Regenerates .ai-context.md |
+| `testing-strategy` | init | coverage (informs), bughunt (informs) | testing-strategy.md |
+| `debug` | init, new-track | implement (fix feeds back) | debug-report.md |
+| `decompose` | init, new-track | implement (optional) | Updates architecture.md; regenerates .ai-context.md |
+| `change` | init, new-track | -- | Modifies spec.md, plan.md |
+| `revert` | init, new-track | -- | Updates tracks.md, git state |
+| `status` | init | standup (reads) | Read-only (tracks.md, plan.md, metadata.json) |
+| `learn` | init | -- | Updates guardrails.md (conventions, anti-patterns) |
+| `adr` | init | deep-review (suggests) | Creates ADR files in draft/adrs/ |
+| `tech-debt` | init | deep-review (suggests), new-track (feeds prioritized items) | draft/tech-debt-report-latest.md |
+| `impact` | init, graph | new-track, implement | Reads graph; emits blast-radius reports |
+| `deploy-checklist` | init | -- | deploy-checklist.md |
+| `incident-response` | init | -- | incident-<timestamp>.md, postmortem-<timestamp>.md |
+| `standup` | init | -- | standup summary (reads status, git log) |
+| `documentation` | init | deep-review (suggests), incident-response (feeds) | Generated docs, runbooks |
+| `index` | init (per-service) | -- | service-index.md, dependency-graph.md, tech-matrix.md |
+| `jira` | new-track | -- | jira-export-latest.md (internal) |
+| `assist-review` | init | -- | Inline PR review assistance |
+| `tour` | init | -- | Read-only architecture walk |
+| `draft` | -- | -- | Navigation only -- references all skills |
+
+## Execution Chains
+
+### Standard Development Flow
+```
+init → new-track → implement → review → (git push + PR)
+                       ↑           |
+                       └───────────┘
+                    (iterate at phase boundaries)
+```
+
+### Bug Fix Flow
+```
+new-track (bug) → debug → implement → review
+                    ↑                      |
+                    └──────────────────────┘ (iterate if fix incomplete)
+```
+
+### Incident Response Flow
+```
+incident-response → debug → implement → review
+        |
+        └→ documentation (post-incident report)
+```
+
+### Operations Flow
+```
+standup ←── status (reads tracks + git log)
+deep-review ──→ tech-debt ──→ new-track (prioritized items)
+```
+
+### Monorepo Flow
+```
+init (per-service) → index (at root) → aggregated context
+```
+
+### Quality Audit Flow
+```
+init → quick-review (fast sanity check)
+init → review (full three-stage)
+init → bughunt (14-dimension sweep)
+init → deep-review (module audit)
+init → testing-strategy → coverage
+init → decompose (optional pre-step for large modules)
+```
+
+### Jira Integration Flow
+```
+new-track → jira (preview / create / review subcommands)
+                ↑
+         bughunt + review reports (optional enrichment)
+```
+
+### Learning Flow
+```
+init → learn → (updates guardrails.md)
+                    ↓
+         All quality skills read guardrails.md
+         (bughunt, review, deep-review, coverage, quick-review)
+```
+
+## Shared Subroutines
+
+| Subroutine | Defined In | Called By |
+|------------|-----------|----------|
+| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage, index |
+| Standard File Metadata (YAML frontmatter) | `init` | All skills that generate draft/ files |
+| Three-Stage Review | `review` | implement (at phase boundaries) |
+| Signal Classification | `init` | init refresh, index (future) |
+| Pattern Learning | `core/shared/pattern-learning.md` | learn, bughunt, review, deep-review (updates guardrails.md) |
+| Context Loading | `core/shared/draft-context-loading.md` | All skills requiring draft/ context |
+| Cross-Skill Dispatch | `core/shared/cross-skill-dispatch.md` | bughunt, deep-review, implement, review |
+| Jira Sync | `core/shared/jira-sync.md` | bughunt, review, implement (when ticket linked) |
+| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, index, impact |
+| Graph Mermaid | `scripts/tools/mermaid-from-graph.sh` | init (injects module-deps + proto-map into architecture.md) |
+
+## Artifact Flow
+
+```
+                    ┌─────────────────────────────────────────────┐
+                    │              draft/.state/                   │
+                    │  freshness.json  signals.json  run-memory   │
+                    └──────────────────┬──────────────────────────┘
+                                       │ read by refresh
+                    ┌──────────────────▼──────────────────────────┐
+                    │              draft/                          │
+  init ──────────►  │  architecture.md ──► .ai-context.md         │
+                    │  product.md  tech-stack.md  guardrails.md   │
+                    │  workflow.md  tracks.md  tech-debt.md       │
+                    │  graph/ (module-graph, hotspots, proto,      │
+                    │         module-deps.mermaid, proto-map..)   │
+                    └──────────────────┬──────────────────────────┘
+                                       │ read by all skills
+           ┌───────────────────────────┼───────────────────────┐
+           ▼                           ▼                       ▼
+    new-track                      bughunt               learn
+    ┌──────────┐              ┌────────────┐        ┌──────────┐
+    │ spec.md  │              │ report.md  │        │guardrails│
+    │ plan.md  │              └─────┬──────┘        │  update  │
+    │metadata  │                    │               └──────────┘
+    └────┬─────┘                    │
+         │                     ┌────┴─────┐
+         ▼                     ▼          ▼
+    implement             jira  debug
+    ┌──────────┐          ┌──────────┐  ┌──────────┐
+    │  code    │          │export.md │  │report.md │
+    │ changes  │          └────┬─────┘  └──────────┘
+    └────┬─────┘               │
+         │                     ▼
+         ▼                (preview/create/review)
+      review              ┌──────────┐
+    ┌──────────┐          │Jira API  │
+    │report.md │          └──────────┘
+    └──────────┘
+```

package/skills/adr/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: adr
+description: Create and manage Architecture Decision Records. Documents significant technical decisions with context, alternatives, and consequences. Also supports evaluate (assess proposals) and design (system design) modes.
+---
+
+# Architecture Decision Records
+
+You are creating or managing Architecture Decision Records (ADRs) for this project.
+
+## Red Flags - STOP if you're:
+
+- Creating an ADR without understanding the decision context
+- Documenting trivial decisions that don't warrant an ADR (e.g., variable naming)
+- Writing an ADR after the fact without capturing the original reasoning
+- Listing alternatives without genuine pros/cons analysis
+- Skipping the "Consequences" section (the most valuable part)
+- Not checking existing ADRs for conflicts or superseded decisions
+
+**ADRs capture WHY, not just WHAT. Every decision needs alternatives considered.**
+
+---
+
+## Pre-Check
+
+1. Verify Draft is initialized:
+```bash
+ls draft/ 2>/dev/null
+```
+
+If `draft/` doesn't exist:
+- Tell user: "Project not initialized. Run `/draft:init` first."
+- Stop here.
+
+2. Check for existing ADR directory:
+```bash
+ls draft/adrs/ 2>/dev/null
+```
+
+If `draft/adrs/` doesn't exist, create it:
+```bash
+mkdir -p draft/adrs
+```
+
+## Step 1: Parse Arguments
+
+Check for arguments:
+- `/draft:adr` — Interactive mode: ask about the decision
+- `/draft:adr "decision title"` — Create ADR with given title
+- `/draft:adr list` — List all existing ADRs
+- `/draft:adr supersede <number>` — Mark an ADR as superseded
+
+### List Mode
+
+If argument is `list`:
+1. Prefer the deterministic `adr-index.sh` wrapper for the listing — it returns a structured JSON `{adrs:[{id,title,date,status,path,related_tracks}]}` derived from each ADR's frontmatter. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
+   ```bash
+   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
+   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+   if [ -x "$DRAFT_TOOLS/adr-index.sh" ]; then
+     bash "$DRAFT_TOOLS/adr-index.sh" --root draft/adrs
+   else
+     ls draft/adrs/ # fallback: enumerate files manually
+   fi
+   ```
+2. Display summary table:
+
+```
+Architecture Decision Records
+
+| # | Title | Status | Date |
+|---|-------|--------|------|
+| 001 | Use PostgreSQL for primary storage | Accepted | 2026-01-15 |
+| 002 | Adopt event-driven architecture | Proposed | 2026-02-01 |
+| 003 | Replace REST with GraphQL | Superseded by #005 | 2026-02-03 |
+```
+
+Stop here after listing.
+
+### Supersede Mode
+
+If argument is `supersede <number>`:
+1. Read the ADR file `draft/adrs/<number>-*.md`
+2. Change status from `Accepted` to `Superseded by ADR-<new_number>`
+3. In the OLD ADR's References section, add: "Superseded by ADR-<new_number>"
+4. Ask what new ADR supersedes it, or create the new one
+5. In the NEW ADR's References section, add: "Supersedes ADR-<old_number>"
+6. Stop here after updating.
+
+### Evaluate Mode
+
+If argument starts with `evaluate`:
+- `/draft:adr evaluate <proposal or description>` — Evaluate a design proposal
+
+1. Read the proposal (from arguments, pasted text, file path, or ask user to describe)
+2. Load project context: `draft/tech-stack.md`, `draft/.ai-context.md`, `draft/architecture.md`
+3. Check existing ADRs in `draft/adrs/` for related decisions
+4. Evaluate against six dimensions:
+   - **Architecture alignment:** Does it fit current patterns?
+   - **Tech stack consistency:** Does it introduce technology not in tech-stack.md?
+   - **Invariant impact:** Does it affect critical invariants from .ai-context.md?
+   - **Scalability:** How does it scale with data/users/team growth?
+   - **Operational complexity:** What new operational burden does it add?
+   - **Team familiarity:** Does the team have experience with this approach?
+
+5. Output evaluation report (do not save to file — display directly):
+
+```
+# Design Evaluation: <Title>
+
+## Summary
+[1-2 sentence assessment]
+
+## Alignment Analysis
+| Dimension | Assessment | Notes |
+|-----------|------------|-------|
+| Architecture alignment | ✅ Aligned / ⚠️ Partial / ❌ Conflict | [detail] |
+| Tech stack consistency | ✅/⚠️/❌ | [detail] |
+| Invariant impact | ✅/⚠️/❌ | [detail] |
+| Scalability | ✅/⚠️/❌ | [detail] |
+| Operational complexity | ✅/⚠️/❌ | [detail] |
+| Team familiarity | ✅/⚠️/❌ | [detail] |
+
+## Risks
+- [Risk and mitigation strategy]
+
+## Recommendation
+[Accept as-is / Accept with modifications / Reconsider approach / Reject — with reasoning]
+
+## Next Steps
+If this leads to a decision: `/draft:adr "<decision title>"` to document it
+If this needs a full design: `/draft:adr design "<system>"` to design it
+```
+
+Stop here after evaluation.
+
+### Design Mode
+
+If argument starts with `design`:
+- `/draft:adr design <system or component>` — Full system/component design
+
+1. Gather requirements:
+   - Ask user or extract from arguments: What does it need to do?
+   - **Functional requirements** — Features and behaviors
+   - **Non-functional requirements** — Scale, latency, availability, cost targets
+   - **Constraints** — Team size, timeline, existing tech stack (from `draft/tech-stack.md`)
+
+2. Load project context: same as ADR creation (Step 3 of main flow)
+
+3. Design using 5-section framework:
+
+   **Section 1: Requirements**
+   - Functional requirements (bulleted list)
+   - Non-functional requirements (table: dimension, target, rationale)
+   - Constraints and assumptions
+
+   **Section 2: High-Level Design**
+   - Component diagram (ASCII)
+   - Data flow description
+   - API contracts (key endpoints/interfaces)
+   - Storage choices with rationale
+
+   **Section 3: Deep Dive**
+   - Data model design (key entities and relationships)
+   - API endpoint design (REST/GraphQL/gRPC with examples)
+   - Caching strategy (what, where, TTL, invalidation)
+   - Queue/event design (if applicable)
+   - Error handling and retry logic
+
+   **Section 4: Scale & Reliability**
+   - Load estimation (requests/sec, data growth)
+   - Scaling strategy (horizontal vs vertical)
+   - Failover and redundancy
+   - Monitoring and alerting requirements
+
+   **Section 5: Trade-off Analysis**
+   - Key trade-offs made (table: decision, alternative, why this choice)
+   - What to revisit as the system grows
+   - Risks and mitigations
+
+4. Determine design document number using same ADR numbering (Step 4 of main flow)
+5. Save to `draft/adrs/<number>-design-<kebab-case-title>.md` with YAML frontmatter and git metadata (same format as ADR creation, Step 5)
+6. Present for review (same as Step 6 of main flow)
+
+Stop here after design.
+
+## Step 2: Gather Decision Context
+
+If in interactive mode (no title provided), ask:
+
+1. "What technical decision needs to be documented?"
+2. "What's the context? What forces are driving this decision?"
+3. "What alternatives did you consider?"
+
+If title provided, proceed directly with the title.
+
+### 2.1 HLD Handoff (when invoked from a track context)
+
+If an active track exists and `draft/tracks/<id>/hld.md` is present:
+
+1. Read HLD §Alternatives Considered table.
+2. If any row is marked `Promote to ADR? yes` and has not been promoted yet (no matching ADR exists), offer:
+   ```
+   Found 1 unpromoted alternative in <track>/hld.md:
+     - {alternative} — rejected because: {reason}
+   Promote to ADR? [Y/n]
+   ```
+3. When promoting:
+   - Pre-fill ADR §Context from HLD §Background and the §High-Level Design / Key Design Decisions row that drove this rejection.
+   - Pre-fill ADR §Decision from the HLD §Key Design Decision that was selected over this alternative.
+   - Pre-fill ADR §Alternatives Considered with the rejected alternative.
+   - Set frontmatter `originating_hld: draft/tracks/<id>/hld.md`.
+4. After ADR creation, edit HLD §Alternatives Considered table: change the `Promote to ADR?` cell to `ADR-<number>` (linking back). Surface the diff to the user for confirmation.
+
+If invoked outside a track context, skip 2.1 and proceed with normal interactive flow.
+
+## Step 3: Load Project Context
+
+Follow the base procedure in `core/shared/draft-context-loading.md`.
+
+Read relevant Draft context:
+- `draft/.ai-context.md` — Current architecture patterns, invariants, data paths, and constraints. Falls back to `draft/architecture.md` for legacy projects.
+- `draft/tech-stack.md` — Current technology choices
+- `draft/product.md` — Product requirements that influence the decision
+
+Cross-reference the decision against existing context:
+- Does it align with documented architecture patterns?
+- Does it introduce a new technology not in tech-stack.md?
+- Does it affect product requirements?
+
+## Step 4: Determine ADR Number
+
+```bash
+# Extract the highest existing ADR number from filenames
+ls draft/adrs/*.md 2>/dev/null | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1
+```
+
+Next number = highest existing ADR number + 1, zero-padded to 3 digits (001, 002, ...). If no ADRs exist, start at 001.
+
+Verify the target filename `draft/adrs/<number>-<kebab-case-title>.md` does not already exist. If collision, increment the number until a free slot is found.
+
+## Step 5: Create ADR File
+
+**MANDATORY: Include YAML frontmatter with git metadata.** Gather git info first:
+
+```bash
+git branch --show-current # LOCAL_BRANCH
+git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "none" # REMOTE/BRANCH
+git rev-parse HEAD # FULL_SHA
+git rev-parse --short HEAD # SHORT_SHA
+git log -1 --format=%ci HEAD # COMMIT_DATE
+git log -1 --format=%s HEAD # COMMIT_MESSAGE
+git status --porcelain | head -1 | wc -l # 0 = clean, >0 = dirty
+```
+
+Create `draft/adrs/<number>-<kebab-case-title>.md`:
+
+```markdown
+---
+project: "{PROJECT_NAME}"
+module: "root"
+adr_number: <number>
+generated_by: "draft:adr"
+generated_at: "{ISO_TIMESTAMP}"
+git:
+  branch: "{LOCAL_BRANCH}"
+  remote: "{REMOTE/BRANCH}"
+  commit: "{FULL_SHA}"
+  commit_short: "{SHORT_SHA}"
+  commit_date: "{COMMIT_DATE}"
+  commit_message: "{COMMIT_MESSAGE}"
+  dirty: {true|false}
+synced_to_commit: "{FULL_SHA}"
+# Optional — populated when ADR is promoted from a track HLD §Alternatives Considered row.
+originating_hld: "{path/to/draft/tracks/<id>/hld.md or null}"
+originating_track: "{<track_id> or null}"
+---
+
+# ADR-<number>: <Title>
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+**Status:** Proposed
+**Deciders:** [names or roles]
+
+## Context
+
+[What is the issue that we're seeing that is motivating this decision or change?]
+[What forces are at play (technical, business, organizational)?]
+
+## Decision
+
+[What is the change that we're proposing and/or doing?]
+[State the decision in active voice: "We will..."]
+
+## Alternatives Considered
+
+### Alternative 1: <name>
+- **Pros:** [advantages]
+- **Cons:** [disadvantages]
+- **Why rejected:** [specific reason]
+
+### Alternative 2: <name>
+- **Pros:** [advantages]
+- **Cons:** [disadvantages]
+- **Why rejected:** [specific reason]
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Trade-off 1]
+- [Trade-off 2]
+
+### Risks
+- [Risk and mitigation]
+
+## References
+
+- [Link to relevant discussion, RFC, or documentation]
+- [Related ADRs: ADR-xxx]
+- [Originating HLD: draft/tracks/<id>/hld.md §Alternatives Considered] (only when promoted from a track)
+```
+
+## Step 6: Present for Review
+
+Present the ADR to the user for review:
+
+```
+ADR-<number> created: <title>
+File: draft/adrs/<number>-<kebab-case-title>.md
+Status: Proposed
+
+Review the ADR and update status to "Accepted" when approved.
+```
+
+## Step 7: Update References (if applicable)
+
+If the decision affects existing Draft context:
+
+1. **tech-stack.md** — If introducing or removing technology, note: "Consider updating draft/tech-stack.md to reflect this decision."
+2. **architecture.md** — If changing architectural patterns, note: "Consider updating `draft/architecture.md` to reflect this decision (`.ai-context.md` will be auto-refreshed via Condensation Subroutine)."
+3. **Superseded ADRs** — If this decision replaces a previous one, update the old ADR's status.
+
+## ADR Status Lifecycle
+
+```
+Proposed → Accepted → [Deprecated | Superseded by ADR-xxx]
+```
+
+- **Proposed** — Decision documented, awaiting review
+- **Accepted** — Decision approved and in effect
+- **Deprecated** — Decision no longer relevant (context changed)
+- **Superseded** — Replaced by a newer decision (link to replacement)
+
+## Error Handling
+
+**If no draft/ directory:**
+- Tell user to run `/draft:init` first
+
+**If ADR number conflict:**
+- Increment to next available number
+- Warn: "ADR-<number> already exists. Using ADR-<next>."
+
+**If superseding non-existent ADR:**
+- Warn: "ADR-<number> not found. Check `draft/adrs/` for valid ADR numbers."