" - Provide recovery: "Manually complete updates: [list specific edits needed]" - Do NOT announce completion until all three files verified consistent 6. Announce: "Track completed! Summary: - Phases: N/N - Tasks: M/M - Duration: [if tracked] [If review ran:] Review: PASS | PASS WITH NOTES | FAIL Report: draft/tracks//review-report-latest.md All acceptance criteria from spec.md should be verified. Next: Run `draft status` to see project overview." ## Error Handling **If blocked:** - Mark task as `[!]` Blocked - Add reason in plan.md - **REQUIRED:** Follow systematic debugging process (see `core/agents/debugger.md`) 1. **Investigate** - Read errors, reproduce, trace (NO fixes yet) 2. **Analyze** - Find similar working code, list differences 3. **Hypothesize** - Single hypothesis, smallest test 4. **Implement** - Regression test first, then fix - Do NOT attempt random fixes - Document root cause when found **Recommended:** Instead of inline debugging, invoke `draft debug` skill for a structured session: ```text "Task blocked: {description}. Run draft debug for structured investigation? [Y/n]" ``` The debug skill provides: Reproduce → Isolate → Diagnose → Fix methodology with debug report output. **If test fails unexpectedly:** - Don't mark complete - Follow systematic debugging process above - Announce failure details with root cause analysis - Show evidence when resolved **If unsure about implementation:** - Ask clarifying questions - Reference spec.md for requirements - Don't proceed with assumptions ## Tech Debt Log During implementation, track technical debt decisions in the track's plan.md: When you encounter a shortcut, workaround, or known-imperfect solution during implementation: 1. Add an entry to the `## Tech Debt` section at the bottom of plan.md 2. Use this format: ```markdown ## Tech Debt | ID | Location | Description | Severity | Payback Trigger | |----|----------|-------------|----------|-----------------| | TD-1 | `src/api/handler.ts:45` | Hardcoded timeout instead of config | Low | When adding config system | | TD-2 | `src/auth/session.ts:12` | In-memory session store | Medium | Before horizontal scaling | ``` **Severity levels:** - **Low** — Cosmetic or minor maintainability issue - **Medium** — Will cause problems at scale or in specific scenarios - **High** — Actively impeding development or risking production issues **Payback Trigger** — The condition or event that should trigger debt repayment (e.g., "before launch", "when adding feature X", "before scaling past N users"). Only log genuine debt — intentional shortcuts with known consequences. Not everything imperfect is debt. --- ## Progress Reporting After each task, report: ```yaml Task: [description] Status: Complete Phase Progress: N/M tasks Overall: X% complete ``` --- ## Cross-Skill Dispatch ### At Track Completion (Step 6) After announcing track completion, suggest relevant follow-ups based on context: **If track modifies production code:** ```text "Track complete! Consider: → draft deploy-checklist — Pre-deployment verification" ``` **If track added new APIs/services/components:** ```text → draft documentation — Update documentation for new components" ``` **If implementation contains TODO/FIXME/HACK comments:** ```text → draft tech-debt — Catalog any new technical debt introduced" ``` **If new patterns or dependencies not in tech-stack.md:** ```text → draft adr — Document this design decision" ``` ### Jira Sync at Completion If Jira ticket linked, sync via `core/shared/jira-sync.md`: - Post comment: "[draft] implementation-complete: All {n} tasks done. Ready for review." ### Bug Track with rca.md If implementing a bug track and `draft/tracks//rca.md` exists: - Load rca.md as context for the implementation - Reference root cause, blast radius, and prevention items during fix - After fix: update rca.md "Proposed Fix" section with actual fix details --- ## Coverage Command When user says "check coverage" or "draft coverage": 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//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:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -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 # Re-resolve helpers (this is a separate Bash session from Step 2). DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools" [ -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: ```yaml --- 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: ```text 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 () — 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 | | | JavaScript/TypeScript | Stryker | | | Python | mutmut | (Mutation testing tool) | | Rust | cargo-mutants | (Mutation testing tool) | | C# | Stryker.NET | | | 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//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: ```text 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: ```text 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//coverage-report-.md` (where `` 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-.md draft/tracks//coverage-report-latest.md ``` Previous timestamped reports are preserved. The `-latest.md` symlink always points to the most recent report. ## Completion Announce: ```text 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//coverage-report-.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 --- ## Deploy Checklist Command When user says "deploy checklist" or "draft deploy-checklist [track ]": You are generating a pre-deployment verification checklist customized to this project's technology stack. ## MANDATORY GRAPH LOOKUP (read before Phase 1) 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. Use the graph to validate module boundaries before the deploy: 1. For each file in the deploy diff, run `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file ` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss. 2. Run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` (and query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off. 3. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — any hotspot in the diff escalates the Resiliency row of Phase 0. Filesystem `grep` is reserved for source-text scans (migration file names, flag-key strings). Module/impact discovery goes through the graph. ## Red Flags — STOP if you're See [shared red flags](../../core/shared/red-flags.md) — applies to all code-touching skills. Skill-specific: - Deploying without a rollback plan - Skipping database migration verification - Deploying on Friday without explicit team approval - Pushing to production without monitoring in place - Ignoring failed checklist items marked as critical **Every deployment needs a rollback plan. No exceptions.** --- ## 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 checklist header. The checklist is scoped 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 — generate a generic checklist. ### 2. Load Draft Context (if available) Read and follow the base procedure in `core/shared/draft-context-loading.md`. ### 3. Run validator gate chain (WS-9) Canonical chain documented in [core/shared/verification-gates.md](../../core/shared/verification-gates.md). A single non-zero exit aborts the checklist and the output groups defects by validator. ```bash TRACK_DIR="$1" # absolute path to track-under-deploy, or . DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools" "$DRAFT_TOOLS/check-track-hygiene.sh" "$TRACK_DIR" || rc=$? "$DRAFT_TOOLS/verify-citations.sh" "$TRACK_DIR" || rc=$? "$DRAFT_TOOLS/verify-doc-anchors.sh" "$TRACK_DIR" || rc=$? "$DRAFT_TOOLS/check-graph-usage-report.sh" "$TRACK_DIR" || rc=$? "$DRAFT_TOOLS/check-scope-conflicts.sh" "$TRACK_DIR/.." || rc=$? "$DRAFT_TOOLS/diff-templates-vs-tracks.sh" "$TRACK_DIR" || rc=$? ``` After the chain runs, write the result into `metadata.json:pre_deploy_status` (`passing` / `failing` / `bypassed`). The downstream checklist sections must not be considered "ready to deploy" if `pre_deploy_status != passing`. ## Step 1: Parse Arguments Check for arguments: - `draft deploy-checklist` — Interactive: detect active track or ask for service name - `draft deploy-checklist ` — Generate checklist for named service - `draft deploy-checklist track ` — Generate from track's change scope If a track is active: read `draft/tracks//spec.md` and `plan.md` for change scope. ## Step 2: Load Context 1. Read `draft/tech-stack.md` — Identify deployment-relevant tech: - Database type (migrations needed?) - Container orchestration (K8s, Docker Compose?) - CI/CD pipeline details - Feature flag system - Monitoring/alerting stack 2. Read `draft/workflow.md` — Deployment conventions, toolchain (git) 3. Read `draft/.ai-context.md` — Service topology, dependencies 4. **If track-scoped:** Read `draft/tracks//hld.md` and `lld.md` if present — these are the source of truth for HLD §Checklist (Performance, Scale, Security, Resiliency, Multi-tenancy, Upgrade, Cost, Flags), §Deployment, §Observability, and LLD §Alerting Thresholds. The deploy checklist validates they are populated. ## Step 3: Generate Checklist Generate a four-phase checklist customized to the project's tech stack. Adapt items based on what the project actually uses — omit irrelevant items (e.g., skip database items if there is no database) and add project-specific items discovered in context. ### Phase 0: HLD/LLD Gate (track-scoped only, when hld.md exists) > **blocker:** the HLD's §Checklist sections were the design-time commitment. If they are still empty at deploy time, the design was never validated against operational reality. This phase enforces that. For `criticality ∈ {high, mission-critical}` (read from `hld.md` frontmatter `classification.criticality`), every row below MUST be checked before Phase 1 begins. For `standard` criticality, missing rows produce warnings but do not block. For `low`, this phase is informational. - [ ] **HLD §Performance** populated — QPS and p95 latency stated - [ ] **HLD §Scale** populated — horizontal scaling story documented; bottlenecks named - [ ] **HLD §Security** populated — credentials, RBAC, encryption answered - [ ] **HLD §Resiliency** populated — failure modes and graceful degradation described - [ ] **HLD §Multi-tenancy** populated — isolation, predictable performance, migration covered - [ ] **HLD §Upgrade** populated — backward compat, dependent service order, blast radius - [ ] **HLD §Flags and Controlled Rollout** populated — flag names, kill switches - [ ] **HLD §Cost Implications** populated — Cloud cost calculation included for SaaS deployments - [ ] **HLD §Deployment** populated — DP/CP platform call answered (on-prem / SaaS / Cloud Console / IBM cloud) - [ ] **HLD §Observability** populated — key metrics named with thresholds - [ ] **HLD §Approvals table** signed by Technical Leads and Architecture Review Board (and Cloud Operations if SaaS, QA if on-prem) — Date column populated - [ ] **LLD §Alerting Thresholds** table populated (when `lld.md` exists) — every metric has Threshold, Severity, Action If any blocker row is empty for high/mission-critical: STOP. Do not generate Phases 1–3, **do not run Step 5 (Save Output)**, and do not create the `deploy-checklist.md` file. Tell the developer: "HLD/LLD §[section] is empty for a [criticality] track. Fill it in `hld.md` / `lld.md` before deploy. Run `draft decompose` to refresh structural sections; author-driven sections must be filled manually." If a partial file is needed for tracking, write it with `status: BLOCKED` in the frontmatter and `_latest` symlinks must NOT be updated — `draft upload` Step 2.5 detects `status: BLOCKED` and refuses to treat the file as a passing checklist. ### Phase 1: Pre-Deploy - [ ] **Tests:** All tests passing in CI - [ ] **Review:** Code reviewed and approved - [ ] **Migrations:** Database migrations tested on staging (if applicable) - [ ] **Migration Rollback:** Down-migration verified (if applicable) - [ ] **Feature Flags:** New features behind flags (if applicable) - [ ] **Config:** Environment variables and secrets verified for target environment - [ ] **Dependencies:** No known vulnerable dependencies (`npm audit` / `pip audit` / equivalent) - [ ] **Monitoring:** Alerting rules configured for new endpoints/services - [ ] **Rollback Plan:** Documented and tested (see Rollback Triggers below) - [ ] **Communication:** Team notified of deployment window - [ ] **Backup:** Database backup taken (if schema changes) - [ ] **Changelog:** Release notes or changelog updated - [ ] **API Compatibility:** Breaking changes documented and consumers notified ### Phase 2: Deploy - [ ] **Method:** [Canary / Blue-Green / Rolling / Direct] — specify strategy - [ ] **Sequence:** Deploy order for multi-service changes documented - [ ] **Monitoring Dashboard:** [URL] open during deployment - [ ] **Smoke Tests:** Ready to run post-deploy - [ ] **Rollback Command:** `[specific rollback command]` ready to execute - [ ] **Health Checks:** Endpoints responding before traffic shift - [ ] **Traffic Shift:** Gradual rollout percentage plan (if canary/blue-green) - [ ] **Deployment Log:** Recording start time and each step completion ### Phase 3: Post-Deploy - [ ] **Smoke Tests:** All passing - [ ] **Error Rate:** Below threshold ([X]% — from baseline) - [ ] **Latency:** Below threshold ([X]ms — p95 from baseline) - [ ] **Logs:** No unexpected errors in first 15 minutes - [ ] **Feature Verification:** New features working as expected - [ ] **Data Integrity:** No data corruption indicators - [ ] **Dependency Health:** Downstream services unaffected - [ ] **Cleanup:** Feature flags toggled, old code paths removed (if applicable) - [ ] **Documentation:** Runbook updated if operational procedures changed - [ ] **Notification:** Team notified of successful deployment ### Rollback Triggers Initiate rollback if ANY of these occur: - Error rate exceeds 2x baseline - p95 latency exceeds 3x baseline - Data corruption detected - Critical user-facing functionality broken - Deployment stuck in partial state for >10 minutes - Health check failures on >10% of instances - Memory or CPU exceeding safe thresholds on deployed instances ### Rollback Procedure 1. Execute rollback command (documented in Phase 2) 2. Verify previous version is serving traffic 3. Confirm error rates return to baseline 4. Investigate root cause before re-attempting deployment 5. Post-mortem if rollback was triggered by data corruption or user impact ## Step 4: Present and Track Present the checklist interactively. For each critical item (marked **bold**): - If unchecked and user wants to proceed: warn "Critical item unchecked: [item]. Are you sure? [y/N]" - Default: stop and address critical items Allow the user to: - Check off items as they complete them - Add custom items specific to this deployment - Mark items as N/A with justification ## Step 5: 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: - Track-scoped: `draft/tracks//deploy-checklist.md` - Standalone: `draft/deploy-checklist-.md` with symlink `deploy-checklist-latest.md` ```bash TIMESTAMP=$(date +%Y-%m-%dT%H%M) # Example: draft/deploy-checklist-2026-03-15T1430.md ln -sf deploy-checklist-${TIMESTAMP}.md draft/deploy-checklist-latest.md ``` ## Mandatory Self-Check (before saving the checklist) Before saving the checklist file, internally verify and report: 1. **Graph files queried** — JSONL files loaded plus any live graph query-tool invocations (`impact`, `cycles`, `modules`). 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 checklist) Emit the canonical footer from [core/shared/graph-usage-report.md](../../core/shared/graph-usage-report.md). The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save. ## Cross-Skill Dispatch - **Auto-invoked by:** `draft upload` (pre-upload verification) - **References:** `core/agents/ops.md` for production-safety mindset - **Jira sync:** If ticket linked, attach checklist and post comment via `core/shared/jira-sync.md` - **MCP:** GitHub MCP for change details, Jira MCP for ticket context ## Error Handling **If no tech-stack.md:** Generate generic checklist with all items, note: "Customize after running `draft init`" **If no active track:** Generate standalone checklist, ask which service/release **If no workflow.md:** Use sensible defaults, recommend documenting deployment conventions --- ## Bug Hunt Command When user says "hunt bugs" or "draft bughunt [--track ]": Conduct an exhaustive bug hunt on this Git repository, enhanced by Draft context when available. ## Primary Deliverable **The bug report is the primary deliverable.** Every verified bug MUST appear in the final report regardless of whether a regression test can be written. Regression tests are a supplementary output — helpful when possible, but never a filter for bug inclusion. ## Relationship to Built-in Bug Hunt Agents Some AI tools (e.g., Claude Code) provide a built-in `bughunt` agent that auto-discovers project structure and runs parallel sweeps. `draft bughunt` is **complementary, not competing**: | | `draft bughunt` | Built-in bughunt agent | |---|---|---| | **Approach** | Context-driven methodology with 14 analysis dimensions and verification protocol | Auto-discovery with parallel sweep subagents | | **Draft context** | Uses architecture, tech-stack, product, guardrails for false-positive elimination | No Draft context awareness | | **Output** | Severity-ranked report with evidence | Inline fixes + regression tests | | **Modifies code** | No (report + regression tests only) | Yes (finds AND fixes) | **When to use which:** Use `draft bughunt` when you need context-aware analysis with structured evidence and false-positive elimination. Use the built-in agent when you want fast parallel sweeps with auto-fix capability. For maximum coverage, run both — `draft bughunt` catches context-specific bugs the built-in misses, and vice versa. ## Red Flags - STOP if you're - Hunting for bugs without reading Draft context first (architecture.md, tech-stack.md, product.md) - Reporting a finding without reproducing or tracing the code path - Fixing production code instead of reporting bugs (bughunt reports bugs and writes regression tests — it doesn't fix source code) - Assuming a pattern is buggy without checking if it's used successfully elsewhere - Skipping the verification protocol (every bug needs evidence) - Making up file locations or line numbers without reading the actual code - Reporting framework-handled concerns as bugs without checking the docs - **Skipping bugs because you can't write a test for them** — mark as N/A and still report **Verify before you report. Evidence over assumptions.** --- ## Pre-Check ### 0. Capture Git Context Before starting analysis, 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 bugs found are relative to this specific branch/commit. ### 1. Load Draft Context (if available) Read and follow the base procedure in `core/shared/draft-context-loading.md`. **Bug-hunt-specific context application:** - Flag violations of intended architecture as bugs (coupling, boundary violations) - Apply framework-specific checks from tech-stack (React anti-patterns, Node gotchas, etc.) - Catch bugs that violate product requirements or user flows - Prioritize areas relevant to active tracks - **Leverage Critical Invariants** — Check for invariant violations across data safety, security, concurrency, ordering, idempotency categories - **Leverage Concurrency Model** — Use thread/async model info for race condition and deadlock analysis - **Leverage Error Handling** — Use failure modes and retry policies for reliability bug detection - **Leverage Data State Machines** — Check for invalid state transitions, missing guard clauses, states with no exit path - **Leverage Storage Topology** — Identify data loss risks at each tier (cache eviction without writeback, event log gaps, missing archive) - **Leverage Consistency Boundaries** — Find bugs at eventual consistency seams (stale reads, lost events, missing reconciliation) - **Leverage Failure Recovery Matrix** — Verify idempotency claims, check for partial failure states without recovery paths - **Leverage Graph Data** (if `draft/graph/` exists) — First resolve the bundled helpers: ```bash # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT} # is not exported into skill Bash). See core/shared/tool-resolver.md. DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools" ``` Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`. - **Leverage Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section. During the bug sweep, when a bug matches a learned anti-pattern, prefix the report entry with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This distinguishes recurring documented patterns from newly discovered bugs, and signals that a systemic fix may be needed rather than a one-off patch. ### 2. Confirm Scope When invoked programmatically by `draft review` with `with-bughunt`, skip scope confirmation and inherit the scope from the calling command. Otherwise, ask user to confirm scope: - **Entire repo** - Full codebase analysis - **Specific paths** - Target directories or files - **Track-level** (specify ``) - Focus on files relevant to a specific track ### 3. Load Track Context (if track-level) If running for a specific track, also load: - [ ] `draft/tracks//spec.md` - Requirements, acceptance criteria, edge cases - [ ] `draft/tracks//plan.md` - Implementation tasks, phases, dependencies Use track context to: - Verify implemented features match spec requirements - Check edge cases listed in spec are handled - Identify bugs in areas touched by the track's plan - Focus analysis on files modified/created by the track If no Draft context exists, proceed with code-only analysis. ## Multi-Directory Mode (monorepo) `draft bughunt` can sweep multiple sub-projects in one run — useful at a monorepo root. Trigger it with an explicit directory list (`bughunt ...`) or no list (auto-discover). 1. **Resolve targets:** - **Explicit list** → use the given directories; verify each exists; skip (with a warning) any that lack a `draft/` directory. - **Auto-discover** → immediate child directories containing a `draft/` folder, excluding `node_modules/`, `vendor/`, `.git/`, `draft/`, and dotfiles. 2. **Run sequentially** (not in parallel — avoids context conflicts): for each target, run the full single-target bug hunt below scoped to that directory. Each writes its own `/draft/bughunt-report-latest.md`. 3. **Aggregate** into `draft/bughunt-summary.md` at the invocation root: a table of `dir | Critical | High | Medium | Low | Total | report link`, a grand total, and a "directories with Critical issues" callout. 4. Report skipped directories (no `draft/`) and suggest running `draft init` in them first. For a single target (the common case), skip this section and proceed. ## Dimension Applicability Check Before analyzing all 14 dimensions, determine which apply to this codebase: - **Skip explicitly** rather than forcing analysis of N/A dimensions - **Mark skipped dimensions** with reason in report summary **Examples of skipping:** - "N/A - no backend code" (skip dimensions 2, 8, 10 for frontend-only repo) - "N/A - no UI components" (skip dimensions 5, 9, 14 for CLI tool) - "N/A - no database" (skip dimension 2 for in-memory app) - "N/A - no external integrations" (skip dimension 8) - "N/A - no external dependencies" (skip dimension 12 for zero-dependency project) - "N/A - no user-facing strings" (skip dimension 14 for libraries/APIs) ## Analysis Dimensions Analyze systematically across all applicable dimensions. Skip N/A dimensions explicitly (see Dimension Applicability Check above). ### 1. Correctness - Logical errors, invalid assumptions, edge cases - Incorrect state transitions, stale or inconsistent UI state - Error handling gaps, silent failures - Off-by-one errors, boundary conditions ### 2. Reliability & Resilience - Crash paths, unhandled exceptions - Reload/refresh behavior, retry logic - UI behavior on partial backend failure - Broken recovery after errors, navigation ### 3. Security - XSS, injection vectors, unsafe rendering - Client-side trust assumptions - Secrets, tokens, auth data exposure - CSRF, insecure deserialization - Path traversal, command injection - **Taint tracking (end-to-end data flow analysis):** - Identify all entry points: HTTP params, form data, file uploads, env vars, CLI args, message queue payloads, webhook bodies - Trace user input to dangerous sinks: SQL queries, shell exec, eval, innerHTML, file path construction, URL construction, deserialization, template rendering - For each sink, verify sanitization/validation exists on every path from source to sink - Flag paths where unsanitized input reaches a sink without passing through a validator, encoder, or sanitizer - Reference: OWASP Top 10, Meta Infer taint analysis methodology ### 4. Performance (Backend + UI) - Inefficient algorithms and data fetching - Blocking work on main/UI thread - Excessive re-renders, unnecessary state updates - Unbounded memory growth (listeners, caches, stores) ### 5. UI Responsiveness & Perceived Performance - Long tasks blocking input - Jank during scrolling, typing, resizing - Layout thrashing, forced reflows - Expensive animations or transitions - Poor loading states, flicker, content shifts ### 6. Concurrency & Ordering - Race conditions between async calls - Stale responses overwriting newer state - Incorrect cancellation or debouncing - Event ordering assumptions - Deadlocks, livelocks ### 7. State Management - Source-of-truth violations - Derived state bugs (computed from stale data) - Global state misuse - Memory leaks from subscriptions or observers - Inconsistent state across components ### 8. API & Contracts - UI assumptions not guaranteed by backend - Schema drift, weak typing, missing validation - Backward compatibility risks - Undocumented API behavior dependencies ### 9. Accessibility & UX Correctness - Keyboard navigation gaps - Focus management bugs - ARIA misuse or absence - Broken tab order or unreadable states - UI behavior that contradicts user intent - Color contrast, screen reader compatibility ### 10. Configuration & Build - Fragile environment assumptions - Build-time vs runtime config leaks - Dev-only code shipping to prod - Missing environment variable validation - CI gaps affecting builds or tests ### 11. Tests - Missing coverage for critical flows - Snapshot misuse (testing implementation, not behavior) - Tests that assert implementation instead of behavior - Mismatch between test and real user interaction - Flaky tests, timing dependencies - **Property-based testing gaps:** pure/mathematical functions without invariant-based tests (e.g., `encode(decode(x)) == x`, sorting idempotency, associativity) - **Test isolation violations:** shared mutable state between test cases (global variables, singletons, class-level state modified in tests without reset) - **Test double misuse:** mocks that leak state across tests, over-mocking (>3 mocks per test suggests testing wiring not behavior), stubs that diverge from real implementation behavior - **Assertion density:** tests with zero or weak assertions (`assertTrue(true)`, `expect(result).toBeDefined()` only, empty catch blocks in test code, `assert result is not None` as sole check) - **Flaky test patterns:** time-dependent assertions (sleep, Date.now, timestamps), port/file system assumptions, test ordering dependencies, non-deterministic data (random seeds, UUIDs without control) ### 12. Dependency & Supply Chain Security - **Known CVEs:** Check dependencies against known vulnerability databases (reference tools: Snyk, Trivy, OWASP Dependency-Check, `npm audit`, `pip-audit`, `cargo audit`, `go vuln`) - **Unpinned dependency versions:** Lockfile freshness, use of version ranges (`^`, `~`, `*`, `>=`) without lockfile enforcement, missing lockfile entirely - **Deprecated packages:** Dependencies with known deprecation notices, archived repositories, or no maintenance activity - **License conflicts:** GPL dependencies in MIT/Apache projects, AGPL in proprietary code, incompatible license combinations in the dependency tree - **Typosquatting risk:** Packages with names similar to popular ones (e.g., `lodahs` vs `lodash`, `reqeusts` vs `requests`), recently published packages with few downloads - **Transitive dependency depth:** Deeply nested dependency chains (>5 levels) increase supply chain attack surface; flag packages that pull in disproportionate transitive trees - Reference: Google OSS-Fuzz, Microsoft SDL, OpenSSF Scorecard ### 13. Algorithmic Complexity - **Quadratic or worse loops:** O(n^2) or worse nested loops over collections (nested `.filter()` inside `.map()`, repeated linear scans, cartesian joins in application code) - **Regex catastrophic backtracking:** Nested quantifiers (`(a+)+`, `(a|a)*`), unbounded repetition with overlapping alternatives — flag any regex applied to user-controlled input - **Unbounded recursion:** Recursive functions without depth limits, missing base cases, or base cases that depend on external/mutable state - **Cache invalidation storms:** Cache miss triggering expensive recomputation that itself invalidates caches, thundering herd on cache expiry without jitter/locking - **Hot path inefficiency:** Sorting/searching in hot paths without appropriate data structures (linear scan where hash map suffices, repeated sorting of same collection, string concatenation in loops) ### 14. Internationalization & Localization - **Hardcoded user-facing strings:** Strings displayed to users embedded directly in source code rather than externalized to resource files/i18n frameworks - **Locale-sensitive operations without locale parameter:** String comparison (`<`, `>`, `localeCompare` without locale), date formatting (`toLocaleDateString` without explicit locale), number formatting, sorting (alphabetical sort that assumes ASCII ordering) - **RTL layout issues:** Hardcoded LTR assumptions in UI code (absolute `left`/`right` positioning, directional margin/padding, text alignment assumptions) - **Unicode handling bugs:** String length vs byte length confusion, missing normalization (NFC/NFD), emoji handling (multi-codepoint sequences split incorrectly, `string.length` vs grapheme count), surrogate pair handling in substring operations ## Bug Verification Protocol **CRITICAL: No bug is valid without verification.** Before declaring any finding as a bug, complete ALL applicable verification steps: ### Verification Checklist (for each potential bug) 1. **Code Path Verification** - [ ] Read the actual code at the suspected location - [ ] Trace the data flow from input to the bug location - [ ] Check if there are guards, validators, or error handlers upstream - [ ] Verify the code path is actually reachable in production 2. **Context Cross-Reference** - [ ] Check `.ai-context.md` (or `architecture.md`) — Is this behavior intentional by design? - [ ] Check `tech-stack.md` — Does the framework handle this case? - [ ] Check `tech-stack.md` `## Accepted Patterns` — Is this pattern explicitly documented as intentional? - [ ] Check `product.md` — Is this actually a requirement violation? - [ ] Check existing tests — Is this behavior already tested and expected? 3. **Framework/Library Verification** - [ ] Read official docs for the specific method/pattern in question - [ ] Quote relevant doc section proving this is/isn't handled - [ ] Check framework version in tech-stack.md (behavior may vary by version) - [ ] Look for middleware, interceptors, or global handlers that may address the issue **Example Framework Documentation Quote:** "React automatically escapes JSX content to prevent XSS (React Docs: Main Concepts > JSX). However, `dangerouslySetInnerHTML` bypasses this protection. Framework version: React 18.2.0 (from tech-stack.md)." 4. **Codebase Pattern Check** - [ ] Search for similar patterns elsewhere in codebase - [ ] If pattern is used consistently, verify it's actually buggy (not just unfamiliar) - [ ] Check if there's a project-specific utility/wrapper that handles the concern 5. **False Positive Elimination** - [ ] Is this dead code that's never executed? - [ ] Is this test/mock/stub code not in production? - [ ] Is this intentionally disabled (feature flag, config)? - [ ] Is there a comment explaining why this appears unsafe but is actually safe? 6. **Pattern Prevalence Check (before reporting)** - [ ] Run Grep to find all occurrences of the pattern - [ ] If found >5x: - Randomly sample 3 instances - Verify they exhibit the same suspected bug - If they work correctly, investigate: what's different about THIS instance? - [ ] If no difference found and other instances work: DO NOT REPORT - [ ] If all instances have the bug: Report with pattern count in "Impact" **Example Pattern Prevalence Check:** ```text 1. Grep: `rg 'dangerouslySetInnerHTML' src/` → found 12 occurrences 2. Sampled 3: src/Blog.tsx:45, src/About.tsx:12, src/FAQ.tsx:30 3. All 3 sanitize input via `DOMPurify.sanitize()` before rendering 4. THIS instance (src/Comment.tsx:88) passes raw user input without sanitization 5. Decision: REPORT — this instance lacks the sanitization all others have ``` ### Confidence Levels Only report bugs with HIGH or CONFIRMED confidence: | Level | Criteria | Action | |-------|----------|--------| | **CONFIRMED** | Verified through code trace, no mitigating factors found | Report as bug | | **HIGH** | Strong evidence, checked context, no obvious mitigation | Report as bug | | **MEDIUM** | Suspicious but couldn't verify all factors | Ask user to confirm before reporting | | **LOW** | Possible issue but likely handled elsewhere | Do NOT report | **Example confirmation prompt for MEDIUM Confidence:** "I found a potential race condition in `src/handler.ts:45` where async state updates may overwrite each other. However, I couldn't verify if there's a locking mechanism elsewhere. Should I report this as a bug?" ### Evidence Requirements Each reported bug MUST include: - **Code Evidence:** The actual problematic code snippet - **Trace:** How data reaches this point (caller chain or data flow) - **Verification Done:** Which checks from the checklist were completed - **Why Not a False Positive:** Explicit statement of why this isn't handled elsewhere ## Analysis Rules - **Do not execute code** - Reason from source only - **Do not assume frameworks "handle it"** - Verify explicitly by checking docs/code - **Do not assume code is buggy** - Verify it's actually reachable and unguarded - **Trace data flow completely** - From input source to bug location - **Cross-reference ALL Draft context** - Check architecture, tech-stack, product, tests - **Check for existing mitigations** - Middleware, wrappers, utilities, global handlers - **Search for patterns** - If used elsewhere without issues, investigate why ## Optional: Runtime Verification (if test suite exists) For suspected bugs that can be tested, write a minimal failing test to confirm: 1. **Write minimal test** — Target the specific bug, not the entire feature 2. **Run test** — Execute and observe failure 3. **Confirm bug** — If test fails as predicted, confidence level increases to CONFIRMED 4. **Only report if**: Test fails OR CONFIRMED confidence from code trace **Example:** ```javascript // Suspected bug: off-by-one in pagination test('should handle last page boundary', () => { const items = Array(100).fill('item'); const result = paginate(items, { page: 10, perPage: 10 }); expect(result.items.length).toBe(10); // Currently returns 9 }); ``` If test fails, upgrade confidence to CONFIRMED and include test in bug report. ## Regression Test Generation For each verified bug, generate a regression test in the project's native test framework that would expose the bug as a failing test. **Before writing any new test**, discover the project's language and test framework, then check whether existing tests already cover the bug scenario (COVERED / PARTIAL / WRONG_ASSERTION / NO_COVERAGE / N/A). If no test framework is detected, mark all bugs `Regression Test Status: N/A` and continue — the bug report is the primary deliverable. **Detailed procedure** — see `references/regression-tests.md` for: - Language and test-framework detection signals (C/C++, Go, Python, JS/TS, Rust, Java) - Existing-test discovery patterns and coverage classification - Test case requirements and language-specific templates - Build/syntax validation commands per toolchain ## Fix Suggestion Generation For each bug with CONFIRMED or HIGH confidence, generate a minimal suggested fix alongside the bug report. Fix suggestions are advisory — they are never auto-applied. ### Fix Generation Rules 1. **Minimal change principle:** The fix must be the smallest code change that addresses the root cause. Do not refactor surrounding code, add features, or improve style. 2. **Before/after format:** Include the exact current code (BEFORE) and the suggested fix (AFTER) as code snippets with file path and line numbers. 3. **Root cause targeting:** The fix must address the root cause identified in the bug's data flow trace, not a symptom. If the root cause is in a different location than the symptom, fix at the root. 4. **Mark as SUGGESTED:** Every fix must be clearly marked as `SUGGESTED (REVIEW REQUIRED)` — never imply auto-application. 5. **One fix per bug:** Each bug gets exactly one suggested fix. If multiple fix strategies exist, choose the most conservative one and note alternatives. 6. **Preserve behavior:** The fix must not change behavior beyond correcting the identified bug. No side-effect improvements. 7. **Skip when inappropriate:** Mark fix as `N/A` for bugs where the fix requires architectural changes, significant refactoring, or domain knowledge beyond what the code provides. Reference: Meta SapFix — automated fix suggestion with human-in-the-loop validation. ## Output Format For each verified bug: ```markdown ### [SEVERITY] Category: Brief Title **Location:** `path/to/file.ts:123` **Confidence:** [CONFIRMED | HIGH | MEDIUM] **Code Evidence:** ```[language] // The actual problematic code ``` **Data Flow Trace:** [How data reaches this point: caller → caller → this function] **Issue:** [Precise technical description of what is wrong] **Impact:** [User-visible effect or system failure mode] **Verification Done:** - [x] Traced code path from [entry point] - [x] Checked architecture.md — not intentional - [x] Verified framework doesn't handle this - [x] No upstream guards found in [files checked] **Why Not a False Positive:** [Explicit statement: "No sanitization exists because X", "Framework Y doesn't escape Z in this context", etc.] **Fix:** [Minimal code change or mitigation] **Suggested Fix (REVIEW REQUIRED):** ```[language] // BEFORE (current buggy code): [exact code snippet from the codebase] // AFTER (suggested fix): [minimal change that addresses root cause] ``` _This fix is SUGGESTED only — human review required before applying. Reference: Meta SapFix methodology._ **Regression Test:** **Status:** [COVERED | PARTIAL | WRONG_ASSERTION | NO_COVERAGE | N/A] **Existing Test:** [`path/to/test_file:line` — test name | None found] [Action: existing test reference, proposed modification, or new test case] ```[language] // New or modified test case (omit if COVERED or N/A) ``` ```text **Example — COVERED (no new test needed):** ```markdown **Regression Test:** **Status:** COVERED — existing test already catches this bug **Existing Test:** `tests/validator_test.cpp:89` — `TEST(Validator, RejectsScriptTags)` No new test needed. Existing test fails when XSS sanitization is removed. ``` **Example — PARTIAL (C++ / GTest):** ```markdown **Regression Test:** **Status:** PARTIAL — tests exist for processInput() but miss unsanitized HTML path **Existing Test File:** `tests/input_test.cpp` **Modification:** Add to existing file: ```cpp TEST(InputSanitization, RejectsMaliciousScript) { std::string malicious = ""; std::string result = processInput(malicious); EXPECT_EQ(result.find("" result = process_input(malicious) assert "" result := ProcessInput(malicious) if strings.Contains(result, "