@drafthq/draft 2.7.0

package/skills/coverage/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: coverage
+description: Compute code coverage for active track or module. Targets 95%+ coverage with report and justification for uncovered lines. Complements TDD workflow.
+---
+
+# Coverage Report
+
+You are computing and reporting code coverage for the active track or a specific module. This complements the TDD workflow — TDD is the process (write test, implement, refactor), coverage is the measurement (how much code do those tests exercise).
+
+## Red Flags - STOP if you're:
+
+- Reporting coverage without actually running the coverage tool
+- Making up coverage percentages
+- Skipping uncovered line analysis
+- Not presenting the report for developer approval
+- Treating this as a replacement for TDD (it's not — TDD stays in `/draft:implement`)
+
+---
+
+## Step 1: Load Context
+
+1. Read `draft/tech-stack.md` for test framework and language info
+2. Find active track from `draft/tracks.md`
+3. If track has `architecture.md` (track-level) or project has `.ai-context.md`, identify current module for scoping
+4. Look for `coverage_target` in `draft/workflow.md`. Check for per-module targets first (see Per-Module Coverage Enforcement below); if absent, default to 95%.
+5. Check if `draft/tracks/<id>/bughunt-report-latest.md` (track scope) or `draft/bughunt-report-latest.md` (project scope) exists for cross-referencing (see Coverage-Bughunt Cross-Reference below)
+
+If no active track and no argument provided:
+- Tell user: "No active track. Provide a path or track ID, or run `/draft:new-track` first."
+
+## Step 2: Detect Coverage Tool
+
+**Preferred:** use the deterministic `detect-test-framework.sh` wrapper — it emits JSON `{languages:[{language,framework,runner_command,test_globs,config_file}]}`. 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"
+[ -x "$DRAFT_TOOLS/detect-test-framework.sh" ] && \
+  bash "$DRAFT_TOOLS/detect-test-framework.sh" --root .
+```
+
+If the script is unavailable or returns `framework: unknown`, fall back to the heuristic table below:
+
+| Language | Coverage Tools |
+|----------|---------------|
+| JavaScript/TypeScript | `jest --coverage`, `vitest --coverage`, `c8`, `nyc` |
+| Python | `pytest --cov`, `coverage run`, `coverage.py` |
+| Go | `go test -coverprofile=coverage.out` |
+| Rust | `cargo tarpaulin`, `cargo llvm-cov` |
+| C/C++ | `gcov`, `lcov` |
+| Java/Kotlin | `jacoco`, `gradle jacocoTestReport` |
+| Ruby | `simplecov` |
+
+**Detection order (fallback path):**
+1. Check `tech-stack.md` for explicit testing section
+2. Check config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `setup.cfg`, `pyproject.toml`, `.nycrc`)
+3. Check `package.json` scripts for coverage commands
+4. If not detectable, ask the developer which tool and command to use
+
+## Step 3: Determine Scope
+
+**Priority order:**
+1. If argument provided (path or module name): use as scope filter
+2. If track has `architecture.md` (or project has `.ai-context.md`) with an in-progress module: scope to that module's files
+3. If active track exists: scope to files changed in the track (use `git diff` against base branch)
+4. Fallback: run coverage for entire project
+
+Build the coverage command with the appropriate scope/filter flags.
+
+## Step 4: Run Coverage
+
+**Preferred:** invoke the normalized `run-coverage.sh` dispatcher — it dispatches to the language-specific runner and emits a normalized JSON `{language,tool,total:{lines,branches},per_file:[{path,lines,branches,uncovered_lines}]}`. This avoids per-language ad-hoc parsing in Step 5.
+
+```bash
+# DRAFT_TOOLS resolved in Step 2 above
+[ -x "$DRAFT_TOOLS/run-coverage.sh" ] && \
+  bash "$DRAFT_TOOLS/run-coverage.sh" --root .
+```
+
+If the script is unavailable or returns `tool: unsupported`:
+1. Execute the coverage command. Request machine-readable output when possible: `--json` for Jest, `--cov-report=json` for pytest, `-coverprofile` for Go, `--coverage-output-format json` for dotnet.
+2. Capture full output
+3. If command fails:
+   - Check if dependencies are installed (test framework, coverage plugin)
+   - Suggest installation command
+   - Ask developer to fix and retry
+
+## Step 5: Parse and Present Report
+
+Parse coverage output and present in a standardized format:
+
+```
+---
+                     COVERAGE REPORT
+---
+Track: [track-id]
+Module: [module name, if applicable]
+Target: [from workflow.md, default 95%]
+
+SUMMARY
+---
+Overall: 87.3% (target: 95%) ← BELOW TARGET
+
+PER-FILE BREAKDOWN
+---
+src/auth/middleware.ts 96.2% PASS
+src/auth/jwt.ts 72.1% FAIL
+src/auth/types.ts 100.0% PASS
+
+UNCOVERED LINES
+---
+src/auth/jwt.ts:45-52 Error handler for malformed token
+src/auth/jwt.ts:78 Defensive null check (unreachable via public API)
+
+---
+```
+
+## Step 6: Branch/Condition Coverage (Optional)
+
+If the project's test framework supports branch/condition coverage (e.g., Istanbul, coverage.py branch mode), execute this step. Otherwise skip to Step 7.
+
+Beyond line coverage, evaluate branch coverage for modules with complex conditional logic:
+
+1. **When to apply:** If the module contains nested conditionals, switch statements, or complex boolean expressions, line coverage alone is insufficient. 100% line coverage can miss untested branches in complex if/else/switch logic.
+2. **Branch coverage** measures whether every branch of every decision point has been exercised. Enable it with the appropriate flag:
+   - Jest/Vitest: `--coverage --coverageReporters=json-summary` (branch data included by default)
+   - pytest: `--cov --cov-branch`
+   - Go: `go test -covermode=count` (counts execution per branch)
+   - JaCoCo: branch coverage reported by default
+   - lcov/gcov: `--rc lcov_branch_coverage=1`
+3. **MC/DC (Modified Condition/Decision Coverage)** — For safety-critical modules (auth, payments, crypto), recommend MC/DC analysis. MC/DC requires that each condition in a decision independently affects the outcome. This is the standard in DO-178C (avionics) and referenced in ISTQB Advanced Test Analyst syllabi.
+   - Present MC/DC gaps separately from standard branch coverage gaps
+   - Flag any boolean expression with 3+ conditions as an MC/DC candidate
+
+Include branch coverage percentage in the report alongside line coverage when branch analysis is performed.
+
+## Step 7: Analyze Gaps
+
+For files below target (using per-module targets when configured — see Per-Module Coverage Enforcement):
+
+1. **Identify uncovered lines** - List specific line ranges and what they contain
+2. **Classify each gap:**
+   - **Testable** - Can and should be covered. Suggest specific test to write.
+   - **Defensive** - Assertions, error handlers for impossible states. Acceptable to leave uncovered.
+   - **Infrastructure** - Framework boilerplate, main entry points. Usually acceptable.
+   - **Legacy/Brownfield** - Modules with 0% or very low coverage that need refactoring. Apply Characterization Testing (see below).
+3. **Suggest tests** for testable gaps:
+   ```
+   SUGGESTED TESTS
+   ─────────────────────────────────────────────────────────
+   1. Test malformed JWT token handling (jwt.ts:45-52)
+      - Input: token with invalid signature
+      - Expected: throws AuthError with code INVALID_TOKEN
+
+   2. Test expired token rejection (jwt.ts:60-65)
+      - Input: token with exp in the past
+      - Expected: throws AuthError with code TOKEN_EXPIRED
+   ```
+
+## Step 7b: Characterization Testing (Brownfield/Legacy Code)
+
+When encountering modules with 0% or very low coverage that need refactoring, do not attempt to write unit tests for untested legacy code directly. Instead, apply the Golden Master / Approval Testing approach (ref: Michael Feathers, "Working Effectively with Legacy Code"):
+
+1. **Create Golden Master baselines** — Generate fixed-seed inputs that exercise the module's public interface. Capture all outputs (return values, side effects, logs) as the approved baseline.
+2. **Lock behavior with approval tests** — Any change that alters the captured output triggers a test failure, making the current behavior explicit and protected.
+3. **Refactor under Golden Master safety net** — With approval tests guarding against regressions, refactor the module incrementally.
+4. **Write proper unit tests via TDD during refactoring** — As you extract and clarify logic, write focused unit tests using RED → GREEN → REFACTOR.
+5. **Remove approval tests** — Once proper unit test coverage meets the target, retire the Golden Master tests.
+
+**Tool references:**
+- ApprovalTests (https://approvaltests.com/) — available for Java, C#, Python, JS, and more
+- Verify (.NET) — snapshot testing library
+
+Present characterization testing recommendations in the gap analysis when applicable.
+
+## Step 7c: Mutation Testing Awareness
+
+After measuring line coverage (and branch coverage if applicable), prompt the engineer to consider mutation testing for critical modules. Mutation testing introduces small code changes (mutants) into the source; if existing tests still pass, the mutant "survived," indicating weak test assertions even at high line coverage.
+
+**When to recommend:** Modules at 90%+ line coverage that are high-risk (auth, payments, crypto, data persistence) or where past bugs have occurred. Mutation testing is most valuable when line coverage is already high but test quality is uncertain.
+
+**Mutation score** = killed mutants / total non-equivalent mutants. Target: 80%+ for critical modules.
+
+**Tool recommendations by language:**
+
+| Language | Tool | Reference |
+|----------|------|-----------|
+| Java | PIT | https://pitest.org/ |
+| JavaScript/TypeScript | Stryker | https://stryker-mutator.io/ |
+| Python | mutmut | (Mutation testing tool) |
+| Rust | cargo-mutants | (Mutation testing tool) |
+| C# | Stryker.NET | https://stryker-mutator.io/ |
+| Go | go-mutesting | (Mutation testing tool) |
+
+**Reference:** Google's mutation testing program is used by 6,000+ engineers and processes approximately 30% of all code diffs, validating that mutation testing scales to large codebases.
+
+Include mutation testing recommendations in the report when applicable, but do not block coverage completion on mutation analysis — it is advisory.
+
+## Step 7d: Coverage-Bughunt Cross-Reference
+
+If a bughunt report exists (`draft/tracks/<id>/bughunt-report-latest.md` or `draft/bughunt-report-latest.md`):
+
+1. **Parse bughunt findings** — Extract file paths and line ranges of confirmed or suspected bugs.
+2. **Cross-reference with uncovered code paths** — Identify bughunt findings that fall in uncovered lines.
+3. **Flag as highest-priority test gaps** — Confirmed bugs in uncovered code are the most dangerous gaps. Present them prominently:
+   ```
+   BUGHUNT CROSS-REFERENCE
+   ─────────────────────────────────────────────────────────
+   ⚠ CRITICAL: Bug "Race condition in session refresh" (bughunt #3)
+     at src/auth/session.ts:112-118 — IN UNCOVERED CODE
+     → Write a test that exposes this bug FIRST before fixing
+
+   ⚠ HIGH: Bug "Missing null check on user lookup" (bughunt #7)
+     at src/users/repository.ts:45 — IN UNCOVERED CODE
+     → Write a regression test targeting this path
+   ```
+4. **Prioritize suggested tests** — Tests that cover bughunt-flagged code should appear first in the SUGGESTED TESTS section.
+
+## Per-Module Coverage Enforcement
+
+Instead of applying a single global coverage target, support differentiated targets by module risk level. Check `draft/workflow.md` for a `coverage_targets` section:
+
+```yaml
+# Example workflow.md configuration
+coverage_targets:
+  high_risk: 95 # auth, payments, crypto, data persistence
+  business_logic: 85
+  infrastructure: 70
+  generated: exclude
+  modules:
+    src/auth/: high_risk
+    src/payments/: high_risk
+    src/crypto/: high_risk
+    src/db/: high_risk
+    src/api/handlers/: business_logic
+    src/utils/: infrastructure
+    src/generated/: generated
+```
+
+**If no per-module configuration exists**, apply these defaults and inform the developer:
+
+| Risk Level | Target | Applies To |
+|------------|--------|------------|
+| High-risk | 95%+ | Auth, payments, crypto, data persistence modules |
+| Business logic | 85%+ | Core domain logic, API handlers |
+| Infrastructure | 70%+ | Utilities, glue code, configuration |
+| Generated | Exclude | Auto-generated code, proto stubs, ORM models |
+
+**Classification heuristic:** Infer module risk from directory names and file content when explicit configuration is absent. Flag the inferred classification in the report so the developer can correct it.
+
+In the coverage report, show per-module targets alongside actual coverage:
+```
+PER-FILE BREAKDOWN (module-level targets)
+---
+src/auth/middleware.ts 96.2% [high_risk: 95%] PASS
+src/auth/jwt.ts 72.1% [high_risk: 95%] FAIL
+src/utils/logger.ts 75.0% [infrastructure: 70%] PASS
+src/generated/api.ts — [generated: excluded]
+```
+
+## Step 8: Developer Review
+
+### CHECKPOINT (MANDATORY)
+
+**STOP.** Present the full coverage report and gap analysis.
+
+Ask developer:
+- Accept current coverage? (if at or above target)
+- Write additional tests for testable gaps?
+- Justify and document acceptable uncovered lines?
+- Adjust coverage target for this track?
+
+**Wait for developer approval before recording results.**
+
+## Step 9: Record Results
+
+After developer approves:
+
+1. **Update plan.md** - Add coverage note to the relevant phase:
+   ```markdown
+   **Coverage:** 96.2% (target: 95%) - PASS
+   - Uncovered: defensive null checks in jwt.ts (justified)
+   ```
+
+2. **Update architecture context** — update the project-level `draft/architecture.md` with coverage data (not a track-level architecture file), then run the Condensation Subroutine (defined in `core/shared/condensation.md`) to regenerate `draft/.ai-context.md`. The Condensation Subroutine only applies to the project-level `draft/architecture.md` → `draft/.ai-context.md` pipeline:
+   ```markdown
+   - **Status:** [x] Complete (Coverage: 96.2%)
+   ```
+
+3. **Update metadata.json** - Add coverage field if not present:
+   ```json
+   {
+     "coverage": {
+       "overall": 96.2,
+       "target": 95,
+       "timestamp": "2025-01-15T10:30:00Z"
+     }
+   }
+   ```
+
+4. **Write detailed coverage report** to `draft/tracks/<id>/coverage-report-<timestamp>.md` (where `<timestamp>` is generated via `date +%Y-%m-%dT%H%M`, e.g., `2026-03-15T1430`) with YAML frontmatter (include `project`, `track_id`, `generated_by: "draft:coverage"`, `generated_at`, `git` metadata matching other skills) and timestamped entries for historical tracking.
+
+   After writing the timestamped report, create a symlink pointing to it:
+   ```bash
+   ln -sf coverage-report-<timestamp>.md draft/tracks/<id>/coverage-report-latest.md
+   ```
+
+   Previous timestamped reports are preserved. The `-latest.md` symlink always points to the most recent report.
+
+## Completion
+
+Announce:
+```
+Coverage report complete.
+
+Overall: [percentage]% (target: [target]%)
+Status: [PASS / BELOW TARGET]
+Files analyzed: [count]
+Gaps documented: [count testable] testable, [count justified] justified
+
+Report: draft/tracks/<id>/coverage-report-<timestamp>.md (symlink: coverage-report-latest.md)
+
+Results recorded in:
+- plan.md (phase notes)
+- architecture.md → .ai-context.md (module status, via Condensation Subroutine) [if applicable]
+- metadata.json (coverage data)
+```
+
+## Re-running Coverage
+
+When coverage is run again on the same track/module:
+1. Compare with previous results from metadata.json. If no previous coverage data found in metadata.json, skip delta comparison and report current values only.
+2. Show delta: "Coverage improved from 87.3% to 96.2% (+8.9%)"
+3. Highlight newly covered lines
+4. Update all records with latest results

package/skills/debug/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: debug
+description: Structured debugging session. Reproduce, isolate, diagnose, and fix bugs using systematic investigation. Invoked by /draft:new-track for bug tracks or directly for ad-hoc debugging.
+---
+
+# Debug
+
+You are conducting a structured debugging session following systematic investigation methodology.
+
+## MANDATORY GRAPH LOOKUP (read before Isolate/Diagnose)
+
+When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. During Steps 3–4 (Isolate, Diagnose):
+
+1. Locate the suspect file's module via `draft/graph/architecture.json` (`.packages`) before tracing data flow.
+2. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
+3. Use `scripts/tools/graph-impact.sh --repo . --file <path>` to size the blast radius before proposing a fix.
+4. Cross-check `draft/graph/hotspots.jsonl` to know whether the file is high-fanIn (any fix needs extra caution).
+
+Filesystem `grep` is reserved for source-text scans (literal error strings, stack-trace symbols when the graph misses). Use the fallback sentence on graph miss.
+
+## Red Flags — STOP if you're:
+
+See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills.
+
+Skill-specific:
+- Making code changes before reproducing the bug
+- Guessing at the cause instead of tracing data/control flow
+- Trying multiple fixes simultaneously ("shotgun debugging")
+- Skipping reproduction steps because "I think I know the issue"
+- Writing tests without asking the developer first (bug/RCA contexts)
+
+**No fixes without root cause investigation first.**
+
+---
+
+## Pre-Check
+
+### 0. Capture Git Context
+
+Before starting, capture the current git state:
+
+```bash
+git branch --show-current # Current branch name
+git rev-parse --short HEAD # Current commit hash
+```
+
+Store this for the debug report header. The session is scoped to this specific branch/commit.
+
+### 1. Verify Draft Context (Optional)
+
+```bash
+ls draft/ 2>/dev/null
+```
+
+Debug can run standalone (without draft context) or within a draft track. If `draft/` exists, load context for richer investigation.
+
+### 2. Load Draft Context (if available)
+
+Read and follow the base procedure in `core/shared/draft-context-loading.md`.
+
+Key context for debugging:
+- `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
+- `tech-stack.md` — Language-specific debugging tools and techniques
+- `guardrails.md` — Known anti-patterns that may be causing the issue
+- `draft/graph/` (MANDATORY when present) — Load `architecture.json` for dependency/module context and `hotspots.jsonl` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
+
+## Step 1: Parse Arguments
+
+Check for arguments:
+- `/draft:debug` — Interactive: ask what's broken
+- `/draft:debug <description>` — Start with the described problem
+- `/draft:debug track <id>` — Debug within a specific track context (load spec.md, plan.md)
+- `/draft:debug <JIRA-KEY>` — Pull context from Jira ticket via MCP
+
+If a Jira ticket is provided:
+1. Pull ticket via Jira MCP: `get_issue()`, `get_issue_description()`, `get_issue_comments()`
+2. Extract: URLs, log paths, stack traces, reproduction steps, affected services
+3. Use `curl`/`wget` to fetch any URLs mentioned (dashboards, error pages, API responses)
+4. Use `ssh` to access log locations on remote nodes (if paths like `/home/log/`, node IPs mentioned)
+5. Collect all gathered data into a triage context bundle
+
+## Step 2: Reproduce
+
+**Goal:** Confirm the bug exists and establish reproduction steps.
+
+1. **Identify the symptom** — Exact error message, unexpected behavior, or performance degradation
+2. **Establish reproduction steps** — Minimum steps to trigger the issue consistently
+3. **Capture evidence** — Error messages, stack traces, log output (verbatim, not summarized)
+4. **Classify reproducibility:**
+   - Always reproducible — proceed to Step 3
+   - Intermittent — document frequency, conditions, patterns (time, load, data-dependent); proceed to Step 3 with the failure mode tagged `intermittent` in the hypothesis log
+   - Cannot reproduce — **halt diagnostic claims.** Do not proceed to Step 4 (Diagnose) until reproduction is established or the user explicitly opts into hypothesis work without reproduction. Hypotheses formed without reproduction routinely converge on confidently-wrong root causes. If the user opts in: every hypothesis must be tagged `unreproduced` and the final report must mark the root cause as `unconfirmed pending repro`.
+
+Reference `core/agents/debugger.md` Phase 1 for detailed investigation techniques.
+
+## Step 3: Isolate
+
+**Goal:** Narrow the failure to a specific code path.
+
+1. **Trace data flow** — Follow data from input to failure point, documenting each hop with `file:line` references
+2. **Trace control flow** — Map the execution path, identify where it diverges from expected behavior
+3. **Differential analysis** — Compare working vs failing cases:
+   | Aspect | Working Case | Failing Case | Difference |
+   |--------|-------------|-------------|------------|
+4. **Check boundaries** — Reference `.ai-context.md` module boundaries to scope the investigation
+
+Reference `core/agents/debugger.md` Phase 2 for language-specific debugging techniques.
+
+## Step 4: Diagnose
+
+**Goal:** Confirm root cause with evidence.
+
+**Ground-truth gate (per hypothesis):** Before forming hypothesis N, **open and Read** the file at the `file:line` you are about to cite. Quote the relevant lines in the hypothesis log. A hypothesis written from graph metadata or recollection is a [Ground-Truth Red Flag](../../core/shared/red-flags.md) G4 violation — it produces hypothesis loops on assumptions rather than evidence.
+
+1. **Form hypothesis** — "The bug is caused by [X] at `file:line` because [evidence quoted from Read]"
+2. **Predict outcome** — "If this hypothesis is correct, then [Y] should be observable"
+3. **Test minimally** — Smallest possible test to prove or disprove
+4. **Record result** — Document in hypothesis log:
+
+| # | Hypothesis (cite + quote) | Test | Prediction | Actual | Result |
+|---|--------------------------|------|-----------|--------|--------|
+| 1 | [description with `path:line` and quoted line] | [test] | [expected] | [actual] | Confirmed/Rejected |
+
+**If hypothesis fails:** Return to Step 3 with updated understanding. After 3 failed cycles, escalate (see Error Handling). Do not increase confidence on a rejected hypothesis just because alternatives are running out — that's how anchoring bias produces wrong root causes.
+
+Reference `core/agents/debugger.md` Phase 3 and `core/agents/rca.md` for 5 Whys analysis.
+
+## Step 5: Fix (with Developer Approval)
+
+**Goal:** Fix the root cause with minimal change.
+
+### Test Writing Guardrail
+
+**STOP.** Before writing any test:
+```
+ASK: "Root cause confirmed: [summary]. Want me to write a regression test for this fix? [Y/n]"
+```
+- If accepted: write regression test first (fails before fix, passes after)
+- If declined: note "Tests: developer-handled" and proceed to fix
+
+### Fix Implementation
+
+1. **Minimal fix** — Address root cause only, no "while we're here" improvements
+2. **Stay in blast radius** — No changes to adjacent modules without explicit approval
+3. **Run existing tests** — Verify no regressions
+4. **Document root cause** — Add findings to Debug Report
+
+## Step 6: Generate Debug Report
+
+**MANDATORY: Include YAML frontmatter with git metadata.** Follow `core/shared/git-report-metadata.md`.
+
+Include the report header table immediately after frontmatter:
+
+```markdown
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+```
+
+Save to:
+- Track-scoped: `draft/tracks/<id>/debug-report.md`
+- Standalone: `draft/debug-report-<timestamp>.md` with symlink `debug-report-latest.md`
+
+```bash
+TIMESTAMP=$(date +%Y-%m-%dT%H%M)
+# Example: draft/debug-report-2026-03-15T1430.md
+ln -sf debug-report-${TIMESTAMP}.md draft/debug-report-latest.md
+```
+
+## Mandatory Self-Check (before debug report)
+
+Before printing the debug report, internally verify and report:
+
+1. **Graph files queried** — JSONL files loaded plus any live graph query-tool invocations.
+2. **Layer 1 files deliberately skipped** — list any context sections skipped.
+3. **Filesystem grep fallback justification** — for every `grep`/`find` run, name the concept it searched for.
+
+If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and use justification `graph data unavailable`.
+
+## Graph Usage Report (append to debug report)
+
+Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md) §Canonical footer. The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+## Cross-Skill Dispatch
+
+- **Auto-invoked by:** `/draft:new-track` (bug tracks — Offer tier), `/draft:implement` (blocked tasks — Offer tier)
+- **Invokes:** RCA agent (`core/agents/rca.md`) for 5 Whys and blast radius analysis
+- **Feeds into:** `/draft:new-track` spec.md (reproduction and root cause sections via Detect+Auto-Feed)
+- **Suggests at completion:**
+  - "Run `/draft:regression` to find the exact commit that introduced this bug"
+  - "Run `/draft:new-track` to create a bug fix track from these findings"
+- **Jira sync:** If ticket linked, attach debug report and post summary via `core/shared/jira-sync.md`
+
+## Error Handling
+
+**If cannot reproduce:** Gather more context — check environment differences, ask for additional logs, check if the issue is environment-specific.
+**If no draft context:** Run standalone with generic debugging methodology. Recommend `/draft:init` for richer context.
+**After 3 failed hypothesis cycles:** Document all findings, list what's been eliminated, escalate — consider architectural review or external input.
+**If MCP unavailable for Jira:** Skip Jira context gathering, proceed with available information.