@drafthq/draft 2.7.0

package/skills/standup/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: standup
+description: Generate standup summary from git history, track progress, and Jira/GitHub activity. Read-only — makes no changes to the codebase.
+---
+
+# Standup
+
+You are generating a standup summary from recent development activity. This is a **read-only** skill — it makes no changes to the codebase or track files.
+
+## Red Flags — STOP if you're:
+
+- Modifying any files (this is read-only)
+- Fabricating activity that didn't happen
+- Including sensitive information (credentials, internal URLs) in standup output
+- Reporting on other people's commits without being asked
+
+**Report facts. Fabricate nothing.**
+
+---
+
+## 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 context. The standup reflects activity up to this specific commit.
+
+### 1. Load Draft Context (if available)
+
+```bash
+ls draft/ 2>/dev/null
+```
+
+If `draft/` exists, read and follow `core/shared/draft-context-loading.md`.
+
+## Step 1: Parse Arguments
+
+Check for arguments:
+- `/draft:standup` — Default: last 24 hours of activity
+- `/draft:standup <days>` — Activity from last N days
+- `/draft:standup weekly` — Full week summary (Monday-Friday)
+- `/draft:standup --author <name>` — Filter to specific author
+
+## Step 2: Gather Activity
+
+### Source 1: Git History
+
+**Preferred:** invoke `parse-git-log.sh` — it parses conventional commits into structured JSONL `{sha,type,scope,track_id,subject,author,timestamp,files_changed}`, eliminating ambiguity in `type(track-id): subject` parsing. 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/parse-git-log.sh" ]; then
+  bash "$DRAFT_TOOLS/parse-git-log.sh" --since "24 hours ago" --author "$(git config user.name)"
+else
+  # Fallback: raw git log
+  git log --oneline --since="24 hours ago" --author="$(git config user.name)"
+  git log --since="24 hours ago" --author="$(git config user.name)" --format="%h %s" --no-merges
+fi
+```
+
+Parse commit messages for:
+- Track IDs (from `type(track-id): description` convention — already extracted as `track_id` in JSONL)
+- Task completions
+- Bug fixes
+- Feature additions
+
+### Source 2: Track Progress (if draft context exists)
+
+Read `draft/tracks.md` for active tracks:
+- Current status and phase
+- Tasks completed since last standup
+- Blockers (tasks marked `[!]`)
+- Scope (`metadata.json:scope_includes` / `scope_excludes`) — mention when
+  two active tracks share a scope tag; surfaced by
+  `scripts/tools/check-scope-conflicts.sh`. Schema:
+  [core/shared/template-contract.md](../../core/shared/template-contract.md).
+
+For each active track, read `plan.md` to determine:
+- Tasks completed (count `[x]` with recent commit SHAs)
+- Current task (first `[ ]` or `[~]`)
+- Phase progress
+
+### Source 3: Jira Activity (if MCP available)
+
+If Jira MCP is available:
+- Query recent ticket transitions (status changes)
+- Check for new comments or assignments
+- Pull sprint board status
+
+### Source 4: GitHub Activity (if MCP available)
+
+If GitHub MCP is available:
+- Query open reviews authored by user
+- Check for new review comments received
+- Query recently merged changes
+
+### Source 5: Skill Metrics (if `~/.draft/metrics.jsonl` exists)
+
+```bash
+tail -50 ~/.draft/metrics.jsonl 2>/dev/null
+```
+
+If the file exists and has records in the standup period, enrich the standup with skill activity:
+- **implement** records: count tasks completed, note TDD pass/fail rate
+- **review** records: note reviews run and their verdicts
+- **bughunt** records: note bug hunts run and critical counts
+- Include a brief "AI-Assisted Activity" line in the standup: `AI tools used: implement (N tasks), review (N times), bughunt (N hunts)`
+
+If the file does not exist or has no records in the period, skip silently — this source is always optional.
+
+## Step 3: Generate Standup
+
+Format using the standard Yesterday/Today/Blockers structure:
+
+```markdown
+## Standup — {date}
+
+**Author:** {git user.name}
+**Period:** {time range}
+
+### Completed
+- [{track-id}] {task description} ({commit SHA})
+- [{track-id}] {task description} ({commit SHA})
+- Reviewed: {GitHub change ID / PR} (if applicable)
+
+### Planned
+- [{track-id}] Next task: {description} (from plan.md)
+- [{track-id}] Continue: {in-progress task} (from plan.md)
+- Review: {pending reviews} (if applicable)
+
+### Blockers
+- [{track-id}] {blocked task description} — {reason}
+- Waiting on: {external dependency}
+
+### Track Progress
+| Track | Phase | Tasks | Status |
+|-------|-------|-------|--------|
+| {id} | {N}/{total} | {done}/{total} | {status} |
+```
+
+**If no activity found:** "No commits in the last {period}. Working on: {active track description from tracks.md or 'no active tracks'}."
+
+## Step 4: Present Output
+
+Present the standup summary directly in the conversation. Do not write to any file unless explicitly requested.
+
+If the user asks to save:
+- Save to `draft/standup-<date>.md`
+- Symlink: `draft/standup-latest.md`
+
+**If saving, 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}` |
+```
+
+## Cross-Skill Dispatch
+
+- **References:** `core/agents/ops.md` for operational context awareness
+- **Reads from:** `/draft:status` data (tracks.md, plan.md, metadata.json)
+- **MCP integrations:** Jira MCP (ticket status), GitHub MCP (review activity)
+- **No downstream dispatch** — this is a terminal, read-only skill
+
+## Error Handling
+
+**If no git history:** "No git commits found for {period}. Is this the right repository?"
+**If no draft context:** Generate standup from git history only. Note: "Richer standups available after `/draft:init`."
+**If no MCP available:** Skip Jira/GitHub sections, generate from local data only.

package/skills/status/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: status
+description: Display current progress of Draft tracks and active tasks. Shows phases, completion percentages, and blocked items.
+---
+
+# Draft Status
+
+Display a comprehensive overview of project progress.
+
+## Red Flags - STOP if you're:
+
+- Reporting status without actually reading the files
+- Making up progress percentages
+- Skipping blocked items in the report
+- Not checking each active track's actual state
+- Summarizing without evidence from the files
+
+**Always read before reporting.**
+
+---
+
+## Gather Data
+
+1. Read `draft/tracks.md` for track list
+2. For each active track, read:
+   - `draft/tracks/<id>/metadata.json` for stats. If `metadata.json` is malformed or unreadable, display `(metadata unavailable)` for that track's statistics instead of failing.
+   - `draft/tracks/<id>/plan.md` for task status
+   - `draft/tracks/<id>/architecture.md` for module status (if exists)
+   - `metadata.json:scope_includes` / `scope_excludes` for the track's
+     scope footprint. Surface these in the status output so reviewers can
+     spot overlap at a glance. Conflicts are detected by
+     `scripts/tools/check-scope-conflicts.sh` (see
+     [core/shared/template-contract.md](../../core/shared/template-contract.md)).
+3. Check for project-wide `draft/.ai-context.md` (or legacy `draft/architecture.md`) for module status
+4. **Detect orphaned tracks:**
+   - Scan `draft/tracks/` for all directories
+   - For each directory, check if it has `metadata.json`
+   - Cross-reference with `draft/tracks.md` entries
+   - If directory has metadata.json but NOT in tracks.md → orphaned track
+   - Collect list of orphaned track IDs for warning section
+
+### Optional: report rollup & freshness signals
+
+If `parse-reports.sh` and `freshness-check.sh` are available, gather structured signals to enrich the status output (severity counts per track, stale `draft/` docs). 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"
+
+# Per-track report severity rollup (bughunt, review, tech-debt, etc.):
+[ -x "$DRAFT_TOOLS/parse-reports.sh" ] && \
+  bash "$DRAFT_TOOLS/parse-reports.sh" --root draft/
+
+# Stale draft/ docs (sha256 drift since last index):
+[ -x "$DRAFT_TOOLS/freshness-check.sh" ] && [ -f draft/.state/freshness.json ] && \
+  bash "$DRAFT_TOOLS/freshness-check.sh" --state draft/.state/freshness.json
+```
+
+Surface non-zero severity counts inline with each track. Surface stale-doc warnings in a "STALE DOCS" section after BLOCKED ITEMS. Both signals are best-effort — skip silently if scripts or state are absent.
+
+## Output Format
+
+Check each track's `metadata.json` `type` field to determine display format.
+
+### Standard (multi-phase) tracks
+
+```
+---
+                      DRAFT STATUS
+---
+PROJECT: [from product.md title]
+
+ACTIVE TRACKS
+---
+[track-id-1] Feature Name
+  Status: [~] In Progress
+  Phase: 2/3 (Phase 2: [Phase Name])
+  Tasks: 5/12 complete
+  ├─ [x] Task 1.1: Description
+  ├─ [x] Task 1.2: Description
+  ├─ [~] Task 2.1: Description ← CURRENT
+  ├─ [ ] Task 2.2: Description
+  └─ [!] Task 2.3: Blocked - [reason]
+
+[track-id-2] Another Feature
+  Status: [ ] Not Started
+  Phase: 0/2
+  Tasks: 0/6 complete
+
+```
+
+### Quick-mode tracks (metadata.json `type` is `"quick"`)
+
+Quick-mode tracks use flat task numbering (`Task 1:`, `Task 2:`) without phases. Display them with a flat task list instead of the phase-grouped tree:
+
+```
+[track-id-3] Quick Feature
+  Status: [~] In Progress
+  Type: quick
+  Tasks: 2/5 complete
+  ├─ [x] Task 1: Description
+  ├─ [x] Task 2: Description
+  ├─ [~] Task 3: Description ← CURRENT
+  ├─ [ ] Task 4: Description
+  └─ [ ] Task 5: Description
+```
+
+Do **not** show `Phase: X/Y` for quick-mode tracks — they have no phases.
+
+### Remaining sections (shared by both formats)
+
+```
+MODULES (if architecture.md exists)
+---
+Module A [x] Complete (Coverage: 96.2%)
+Module B [~] In Progress - 3/5 tasks
+Module C [ ] Not Started
+
+BLOCKED ITEMS
+---
+- [track-id-1] Task 2.3: [blocked reason]
+
+ORPHANED TRACKS
+---
+⚠ The following tracks have metadata.json but are missing from tracks.md:
+- draft/tracks/orphan-track-id/
+
+Recovery options:
+1. Add to tracks.md manually if track is valid
+2. Remove orphaned track directory if no longer needed
+
+RECENTLY COMPLETED
+---
+- [track-id-3] - Completed [date]
+
+QUICK STATS
+---
+Active Tracks: 2
+Total Tasks: 18
+Completed: 5 (28%)
+Blocked: 1
+---
+```
+
+## Module Reporting
+
+When `.ai-context.md` or `architecture.md` exists for a track (track-level or project-level):
+
+1. Read the `.ai-context.md` (or `architecture.md`) module definitions from `## Modules` section
+2. For each module, determine status from its status marker:
+   - `[ ]` Not Started
+   - `[~]` In Progress — count completed vs total tasks mapped to this module
+   - `[x]` Complete — include coverage percentage if recorded
+   - `[!]` Blocked — include reason
+3. Display in the MODULES section of the track report
+4. If project-wide `draft/.ai-context.md` (or legacy `draft/architecture.md`) exists, show a project-level module summary after QUICK STATS
+
+---
+
+## If No Tracks
+
+```
+---
+                      DRAFT STATUS
+---
+PROJECT: [from product.md title]
+
+No active tracks.
+
+Get started:
+  /draft:new-track "Your feature description"
+
+---
+```
+
+## If Not Initialized
+
+```
+Draft not initialized in this project.
+
+Run /draft:init to initialize.
+```

package/skills/tech-debt/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: tech-debt
+description: Identify, categorize, and prioritize technical debt across seven dimensions. Generates remediation plans with effort estimates. Offered by /draft:new-track for refactor tracks.
+---
+
+# Tech Debt
+
+You are conducting a technical debt analysis to catalog, prioritize, and plan remediation of debt across the codebase.
+
+## MANDATORY GRAPH LOOKUP (read before debt scan)
+
+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. Tech-debt prioritization is fundamentally driven by graph data:
+
+1. Load `draft/graph/hotspots.jsonl` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
+2. Read `draft/graph/architecture.json` (`.packages`) and run `scripts/tools/cycle-detect.sh --repo .` — flag debt in modules involved in cycles as higher priority.
+3. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate dependency cycles — every cycle is a candidate architecture-debt entry.
+4. For each catalogued finding, run `scripts/tools/graph-impact.sh --repo . --file <path>` so the remediation plan includes blast-radius.
+
+Filesystem `grep` (e.g. `scan-markers.sh`) is still primary for TODO/FIXME marker discovery — markers are source-text, not graph-derived. The graph governs **prioritization**, the marker scan governs **discovery**.
+
+## Red Flags — STOP if you're:
+
+See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills.
+
+Skill-specific:
+- Flagging intentional design choices as debt (check tech-stack.md accepted patterns first)
+- Cataloging debt without understanding the business context
+- Setting priorities without considering team capacity
+- Recommending "rewrite from scratch" without exhausting incremental options
+- Ignoring the existing guardrails.md conventions
+
+**Not all shortcuts are debt. Check accepted patterns before flagging.**
+
+---
+
+## 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 report header. All findings are relative to this specific branch/commit.
+
+### 1. Verify Draft Context
+
+```bash
+ls draft/ 2>/dev/null
+```
+
+If `draft/` doesn't exist, this skill can still run standalone with reduced context.
+
+### 2. Load Draft Context (if available)
+
+Read and follow the base procedure in `core/shared/draft-context-loading.md`.
+
+## Step 1: Parse Arguments
+
+- `/draft:tech-debt` — Project-wide scan (default)
+- `/draft:tech-debt module <name>` — Module-scoped scan
+- `/draft:tech-debt category <type>` — Filter by category (code, architecture, test, dependency, documentation, infrastructure)
+- `/draft:tech-debt <path>` — Scan specific directory/file pattern
+
+## Step 2: Load Context
+
+1. Read `draft/tech-stack.md` — **Critical:** "Accepted Patterns" section. Do NOT flag these as debt.
+2. Read `draft/guardrails.md` — Learned conventions (skip) and anti-patterns (always flag)
+3. Read `draft/.ai-context.md` — Module boundaries, invariants, known constraints
+4. Read `draft/product.md` — Business priorities for impact assessment
+5. Read `draft/workflow.md` — Team conventions and toolchain for feasibility assessment
+
+## Step 3: Scan for Debt
+
+Scan the codebase systematically across all seven categories. For each finding, record: location (file:line OR track id for Process Debt), description, evidence, and category.
+
+### Category 1: Code Debt
+
+For TODO/FIXME/HACK/XXX/DEPRECATED markers, prefer the deterministic `scan-markers.sh` wrapper — it emits JSON `[{path,line,marker,text,sha,author,introduced,age_days}]` with blame ages already computed. 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/scan-markers.sh" ] && bash "$DRAFT_TOOLS/scan-markers.sh" --root .
+# Fallback when script unavailable: grep -rn 'TODO\|FIXME\|HACK\|XXX\|DEPRECATED' .
+```
+
+Use the JSON output to prioritise: markers with `age_days > 180` are stale and should be promoted to tracked tech debt.
+
+**Marker context gate (Ground-Truth Discipline G1):** `scan-markers.sh` produces *candidates*, not findings. Before promoting a TODO/FIXME/HACK/XXX/DEPRECATED marker to your debt catalog, **Read** the surrounding 10–20 lines at that `file:line`. Many markers are justified (intentional deferrals with ownership) or already addressed (the marker rotted, the work shipped). A debt entry whose Evidence is "marker exists" without a Read is a Ground-Truth Red Flag — produce false positives and reviewer churn.
+
+- Complex functions (cyclomatic complexity >10, deep nesting >4 levels)
+- Duplicated code blocks (>20 lines similar across multiple locations)
+- TODO/FIXME/HACK/XXX comments (especially old ones — check git blame age via `scan-markers.sh` above)
+- Dead code (unreachable branches, unused exports, commented-out blocks)
+- Inconsistent naming patterns within the same module
+- Long functions (>100 lines without clear separation of concerns)
+- God classes (>500 lines, >10 public methods, mixed responsibilities)
+- Magic numbers and hardcoded strings that should be constants
+- Deeply nested callbacks or promise chains (callback hell)
+
+### Category 2: Architecture Debt
+
+- Dependency cycles between modules (A depends on B depends on A)
+- Tight coupling (modules with >5 direct cross-references)
+- Layer violations (UI calling DB directly, business logic in controllers)
+- Missing abstractions (repeated patterns without shared interface)
+- Monolith tendencies (single module >50% of codebase)
+- Inconsistent data flow patterns (some modules use events, others direct calls)
+- Missing or bypassed API boundaries (internal implementation details exposed)
+- Configuration scattered across multiple locations
+
+### Category 3: Test Debt
+
+- Modules with zero test coverage
+- Missing integration tests for service boundaries
+- Brittle tests (frequently failing, time-dependent, order-dependent)
+- Test-code coupling (tests that break on internal refactor, not behavior change)
+- Missing E2E tests for critical user flows (from product.md)
+- Tests with no assertions (tests that only check "doesn't throw")
+- Disabled/skipped tests without justification
+- Missing test fixtures or shared test utilities (repeated setup code)
+
+### Category 4: Dependency Debt
+
+- Outdated dependencies (>2 major versions behind)
+- Known security vulnerabilities (check advisories: `npm audit`, `pip audit`, etc.)
+- Deprecated APIs in use (check dependency changelogs)
+- Version conflicts or pinning issues
+- Abandoned dependencies (no updates >2 years, archived repos)
+- Overly broad dependency versions (no pinning in production)
+- Unnecessary dependencies (functionality available in stdlib or already-included packages)
+
+### Category 5: Documentation Debt
+
+- Undocumented public APIs (exported functions/classes without docstrings)
+- Stale README (doesn't match current setup steps or architecture)
+- Missing architecture decision records for non-obvious choices
+- Outdated onboarding documentation
+- Missing runbooks for production services
+- API docs out of sync with implementation
+- Missing inline comments for complex algorithms or business rules
+
+### Category 6: Infrastructure Debt
+
+- Manual deployment steps (should be automated)
+- Missing or insufficient monitoring (services without health checks or alerts)
+- Hardcoded configuration (should be environment variables)
+- Missing CI checks (linting, security scanning, type checking)
+- No automated backup/restore verification
+- Missing or outdated Dockerfiles / container configs
+- Inconsistent environment parity (dev/staging/prod divergence)
+- Missing rate limiting or resource guards on public endpoints
+
+### Category 7: Process Debt ( HLD/LLD compliance)
+
+Scan `draft/tracks/*/` for design-process gaps. For each track:
+
+- Read `spec.md` frontmatter `classification.criticality`. Default to `standard` if absent.
+- Check for `hld.md`:
+  - Missing for `criticality ∈ {standard, high, mission-critical}` → flag as Process Debt
+  - Severity: `critical` for mission-critical, `high` for high, `medium` for standard
+  - Remediation: "Run `/draft:decompose <track>` to generate hld.md"
+- Check `hld.md` Approvals table:
+  - Required rows unsigned (per `/draft:upload` Step 3.1 logic) and the track has merged commits → flag
+  - Severity: `high` if criticality ∈ {high, mission-critical}, `medium` otherwise
+  - Remediation: "Re-circulate hld.md to listed approvers; update Date column on sign-off"
+- Check for `lld.md`:
+  - Any module in HLD §Detailed Design has `Complexity: High` AND `lld.md` is missing → flag
+  - Severity: `medium`
+  - Remediation: "Run `/draft:decompose <track> --lld`"
+- Check HLD §Checklist completeness:
+  - For criticality ≥ standard: any §Checklist sub-section still showing the placeholder text "<Describe..." or empty bullets → flag as Process Debt
+  - Severity: `high` for high/mission-critical, `medium` for standard
+  - Remediation: "Author must populate hld.md §Checklist before /draft:deploy-checklist will pass"
+- Check HLD/LLD freshness:
+  - If `synced_to_commit` is older than the latest merged commit touching files in HLD §Detailed Design → flag as drift
+  - Severity: `medium`
+  - Remediation: "Run `/draft:decompose <track>` to refresh graph slots; review structural sections; re-circulate if signed"
+
+Process Debt findings carry the same Impact/Effort/Risk scoring as other categories. They surface in the remediation plan alongside code/architecture debt.
+
+## Step 4: Prioritize
+
+For each finding, score on three dimensions:
+
+- **Impact** (1-5): How much does this hurt development velocity or production reliability?
+  - 1: Minor annoyance, cosmetic
+  - 2: Slows development occasionally
+  - 3: Regular friction, workarounds needed
+  - 4: Significant velocity drag or reliability risk
+  - 5: Blocking progress or causing incidents
+
+- **Risk** (1-5): How likely is this to cause a production incident?
+  - 1: Extremely unlikely
+  - 2: Unlikely but possible
+  - 3: Moderate likelihood
+  - 4: Likely under certain conditions
+  - 5: Near-certain or already causing issues
+
+- **Effort** (1-5): How much work to remediate?
+  - 1: Hours (quick fix)
+  - 2: A day or two
+  - 3: A sprint (1-2 weeks)
+  - 4: Multiple sprints
+  - 5: Large project (months)
+
+**Priority = (Impact + Risk) / (6 - Effort)**
+
+Higher score = higher priority. This formula naturally favors high-impact, low-effort items ("quick wins") and deprioritizes low-impact, high-effort items.
+
+## Step 5: Generate Remediation Plan
+
+Organize findings into three actionable tiers:
+
+### Tier 1: Quick Wins (Priority > 3, Effort <= 2)
+
+Items that can be fixed in a single sprint or less. Do these first — they deliver the best return on investment.
+
+For each item:
+- Specific fix description
+- Estimated time (hours)
+- Suggested assignee pattern (e.g., "whoever touches this module next")
+
+### Tier 2: Strategic Improvements (Priority > 2, Effort > 2)
+
+Items requiring dedicated effort. Create via `/draft:new-track` or route via `/draft:jira` (or `/draft:plan "tech debt remediation"`).
+
+For each item:
+- Scope and approach
+- Estimated effort (sprints)
+- Dependencies and sequencing
+- Risk of deferral (what happens if we wait?)
+
+### Tier 3: Nice-to-Haves (Priority <= 2)
+
+Track but don't prioritize. Revisit quarterly. These items are real debt but the cost of remediation exceeds the current pain.
+
+## Step 6: Save Output
+
+**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: `draft/tech-debt-report-<timestamp>.md`
+Create symlink: `draft/tech-debt-report-latest.md`
+
+```bash
+TIMESTAMP=$(date +%Y-%m-%dT%H%M)
+# Example: draft/tech-debt-report-2026-03-15T1430.md
+ln -sf tech-debt-report-${TIMESTAMP}.md draft/tech-debt-report-latest.md
+```
+
+Report structure:
+1. **Executive Summary** — Total findings by category and priority tier, headline stats
+2. **Priority Matrix** — Table of all findings sorted by priority score
+3. **Category Details** — Per-category findings with file locations and evidence
+4. **Remediation Plan** — Three tiers with effort estimates
+5. **Recommendations** — Strategic advice on debt management practices
+
+## Report Closing: Next Actions (REQUIRED)
+
+Every tech-debt report must end with a `## Next Actions` section listing the smallest set of follow-ups in execution order. Use this exact shape:
+
+```markdown
+## Next Actions
+
+| # | Action | Owner | Blocker? | Skill / Command |
+|---|---|---|---|---|
+| 1 | <imperative one-liner> | <team\|TBD> | yes/no | `/draft:<skill> <args>` or `n/a` |
+```
+
+Rules:
+- Tech-debt rarely "blocks" merge; mark `Blocker? = yes` only for items that will cause an outage on next deploy.
+- Suggest `/draft:new-track` for items >1 day of work, `/draft:adr` for design re-decisions, `/draft:implement` for surgical cleanups.
+- Cap at 10 actions; full backlog stays in the report body.
+
+## Mandatory Self-Check (before debt report)
+
+Before printing the final debt report, internally verify and report:
+
+1. **Graph files queried** — JSONL files loaded plus any live graph query-tool invocations (especially `cycles` and `impact`).
+2. **Layer 1 files deliberately skipped** — list any context sections skipped as irrelevant to the categories scanned.
+3. **Filesystem grep fallback justification** — for every `grep`/`find` run beyond `scan-markers.sh`, 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 debt 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
+
+- **Offered by:** `/draft:new-track` (refactor tracks — scope the debt before planning)
+- **Suggested by:** `/draft:implement` (when TODO/FIXME detected at completion)
+- **Suggested by:** `/draft:deep-review` (architecture debt findings)
+- **Feeds into:** `/draft:jira` (or `/draft:plan` for remediation tracks) (create remediation tickets from Tier 2 items)
+- **Feeds into:** `/draft:testing-strategy` (Test Debt findings inform test planning)
+- **Jira sync:** If ticket linked, attach report and post summary via `core/shared/jira-sync.md`
+
+## Error Handling
+
+**If no draft context:** Run with reduced analysis, note: "Run `/draft:init` for better debt detection with accepted-pattern filtering"
+**If tech-stack.md has accepted patterns:** Explicitly skip those patterns, note: "Skipped N accepted patterns from tech-stack.md"
+**If >100 findings:** Group by category, show top 20 by priority in the summary, full list in Category Details section
+**If module scope requested but module not found:** List available modules, ask user to confirm