@drafthq/draft 2.7.0

package/skills/deep-review/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: deep-review
+description: Single-module production readiness audit (ACID, resilience, observability). Use to audit one service/module end-to-end — NOT for diff/PR review (use review / quick-review) or bug-finding sweeps (use bughunt).
+---
+
+# Deep Review — Production-Grade Module Audit
+
+Perform an exhaustive end-to-end lifecycle review of a service, component, or module. Ensure ACID compliance and production-grade enterprise quality. Unlike standard review commands, this operates strictly at the module level.
+
+## 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. Deep-review uses the graph to **narrow review scope** — a key 30–50% scope reduction:
+
+1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `architecture.json` for the audited module's structure — do not enumerate via `find`.
+2. Run `scripts/tools/graph-impact.sh --repo . --file <each-changed-file>` per file in the diff (or per file in the module if no diff) to obtain the affected module set deterministically.
+3. Run `scripts/tools/cycle-detect.sh --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
+4. Cross-check `draft/graph/hotspots.jsonl` to identify high-fanIn files inside the module — these get deeper inspection.
+
+Filesystem `grep` is reserved for source-text scans (API contract strings, secret patterns, log message audits). Module enumeration and caller tracing go 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:
+- Acting without reading the Draft context (`draft/.ai-context.md`, `draft/tech-stack.md`, `draft/product.md`)
+- Modifying production code. This command is for auditing and reporting only. Fixes should be handled in a separate implementation track.
+- Reviewing a module that was already reviewed recently, unless explicitly requested.
+
+---
+
+## Arguments
+
+- `$ARGUMENTS` — Optional: explicit module/service/component name (directory) to review. If omitted, auto-select the next unreviewed module.
+
+---
+
+## Step 0: Verify Draft Context
+
+```bash
+ls draft/.ai-context.md 2>/dev/null
+```
+
+If `draft/` does not exist: **STOP** — "No Draft context found. Run `/draft:init` first. Deep review requires `draft/.ai-context.md` and `draft/tech-stack.md` to evaluate against project standards."
+
+If `.ai-context.md` is missing, check for `draft/architecture.md` as a fallback (per `core/shared/draft-context-loading.md`).
+
+---
+
+## Module Selection
+
+1. **Check review history:** Read `draft/deep-review-history.json` if it exists. This file tracks previously reviewed modules with timestamps.
+2. **If `$ARGUMENTS` is provided:** Use that module. If it was previously reviewed, re-review it (the user explicitly requested it).
+3. **If no argument:** Discover all modules using the following priority order:
+   1. Use module definitions from `draft/.ai-context.md` if it exists (check `## Modules` or `## Module Catalog` sections).
+   2. Use top-level directories under `src/` or equivalent source root.
+   3. Use directories containing `__init__.py`, `package.json`, or `go.mod`.
+   Document which heuristic was used in the report.
+   Select the first module NOT present in the review history. If all have been reviewed, pick the one with the oldest review date.
+4. **Announce selection:** State which module was selected and why before proceeding.
+
+---
+
+## Review Phases
+
+### Phase 1: Context & Structural Analysis
+- Load Draft context following the procedure in `core/shared/draft-context-loading.md`. Use loaded context to understand intended boundaries and critical invariants.
+- **Load track HLD/LLD if any track owns this module.** Scan `draft/tracks/*/hld.md` for §Detailed Design components matching the module path. When found, extract claims from §High-Level Design / Key Design Decisions, §Checklist (Performance/Scale/Security/Resiliency/Multi-tenancy/Upgrade/Cost), §Observability, §Deployment, and any LLD §Classes and Interfaces invariants and §Error Handling policies. These claims become the design contract this audit measures against (HLD claims vs code reality).
+- **Load Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section before analysis begins. During the audit, when an issue matches a learned anti-pattern, prefix the finding with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This separates newly discovered issues from documented recurring patterns and allows the report to recommend systemic remediation rather than isolated fixes.
+- Map the module's full dependency graph (imports, injected services, external calls)
+- Trace the complete lifecycle: initialization → processing → persistence → cleanup
+- Identify all entry points and exit paths
+- Catalog all state mutations and side effects
+- **API Contract Drift Detection:** Compare the module's actual code interfaces against documented contracts (OpenAPI/Swagger specs, Protobuf/gRPC definitions, GraphQL schema files, TypeScript type exports). Flag drift: endpoints that exist in code but not in the spec (or vice versa). Flag type mismatches between spec and implementation. Reference: Amazon, Google large-scale changes.
+
+### Phase 2: ACID Compliance Audit
+
+> Rule references: `[CQ-006, CQ-007, CQ-008]` error/exception context, `[SEC-03]` SQL parameterization, `[RC-004, RC-005]` data integrity & concurrency. Cite the rule ID in each finding.
+
+Every ACID finding ("missing rollback", "fire-and-forget write", "race condition", "no isolation guarantee") must cite the closest applicable rule range (e.g., `[RC-004..RC-005]` for data integrity, `[CQ-006..CQ-008]` for error context, `[SEC-03]` for SQL safety).
+
+**Evidence requirement (Ground-Truth Discipline G1, G4):** Every ACID finding ("missing rollback", "fire-and-forget write", "race condition", "no isolation guarantee") must cite `file:line` AND include a quoted code snippet showing the issue. A finding that says "no transactions found in module X" without quoting the code site is a graph-metadata claim, not an audit result — discard it. "Verify" and "Check" below mean *Read the candidate sites*, not "scan for keywords."
+
+- **Atomicity:** Verify all multi-step operations are wrapped in transactions. Partial failure must not leave corrupt state. Check for missing rollback paths. `[RC-004]`
+- **Consistency:** Validate all invariants, constraints, and business rules are enforced before and after every state transition. Check schema validation, data type enforcement, and boundary conditions. `[CQ-006, RC-003]`
+- **Isolation:** Check for race conditions, shared mutable state, concurrent access without locking/synchronization. Verify transaction isolation levels where databases are involved. `[RC-005]`
+- **Durability:** Confirm committed data survives crashes. Check for fire-and-forget patterns, missing flush/sync calls, and inadequate error handling around persistence. `[CQ-007, CQ-008]`
+- **Event Sourcing:** Are events immutable? Is event replay idempotent? Is the event store append-only?
+- **CQRS:** Are read/write models eventually consistent? Is consistency lag acceptable for the use case?
+- **Saga Pattern:** Are compensating transactions defined for each step? What happens on partial saga failure?
+- **Eventual Consistency:** Are there convergence guarantees? How is conflict resolution handled (LWW, CRDT, manual)? Reference: Amazon distributed systems.
+
+### Phase 3: Production-Grade Assessment
+
+**Applicability note:** Skip categories that are not applicable to the module type (e.g., circuit breakers and backpressure are backend-specific; skip for frontend/CLI modules).
+
+> Rule references: `[RC-008, RC-009, RC-010]` observability & logging, `[SEC-04, SEC-06]` network/process boundaries, `[SEC-05]` secrets, `[RC-015]` config validation, `[CQ-006..CQ-008]` error context. Cite the rule ID in each finding.
+
+Every finding in this phase must cite the relevant rule range (e.g., `[RC-008..RC-010]` for observability, `[SEC-04, SEC-06]` for network/process boundaries, `[RC-015]` for configuration).
+
+- **Resilience:** Graceful degradation, circuit breakers, timeout handling, backpressure `[RC-005]`
+- **Observability:** Logging coverage (not excessive), structured log fields, correlation IDs, metric emission points `[RC-008, RC-009, RC-010]`
+  - **Structured logging:** Are logs structured (JSON/key-value) vs free-form strings?
+  - **Log level correctness:** Are ERROR/WARN/INFO/DEBUG used appropriately? Are expected conditions logged at DEBUG, not ERROR?
+  - **PII leakage:** Do logs or error messages expose personally identifiable information, tokens, or credentials? `[SEC-05, RC-010]`
+  - **Tracing spans:** Are spans created at service boundaries? Do spans include relevant attributes (user_id, request_id)?
+  - **Metric cardinality:** Are metric labels bounded? Unbounded labels (e.g., user_id as label) cause metric explosion.
+  - **Alerting coverage:** Are critical failure modes covered by alerts? Are there runbooks linked to alerts?
+  - Reference: Netflix Full Cycle Developers, Google SRE.
+- **Configuration:** Hardcoded values that should be configurable, missing environment variable validation `[RC-015, SEC-05]`
+- **State Lifecycle:** Memory accumulation, zombie processes, dropped messages
+- **SLO/SLA Alignment:**
+  - Does the module's observed/expected error rate match defined SLOs?
+  - **Latency profiles:** Are p50, p95, p99 latency targets defined and achievable?
+  - **Error budget:** What percentage of the error budget has been consumed? Is the module in "protect" or "innovate" mode?
+  - **Availability:** Does the module's uptime target (99.9%, 99.99%) match its actual architecture?
+  - If no SLOs are defined, recommend defining them. Reference: Google SRE (https://sre.google/sre-book/service-level-objectives/).
+- **Database Schema Analysis:**
+  - **Missing indexes:** Queries filtering/joining on unindexed columns.
+  - **Wide table scans:** SELECT * or queries without WHERE clauses on large tables.
+  - **Schema constraints:** Missing NOT NULL, UNIQUE, FOREIGN KEY constraints.
+  - **Migration safety:** Can migrations run without downtime? Are they backward-compatible?
+  - **N+1 at schema level:** Relationships that require multiple queries instead of joins.
+  - Reference: Google large-scale changes.
+
+### Phase 3.5: HLD/LLD Claims vs Code Reality (when HLD found in Phase 1)
+
+> Rule references: `[RC-012]` API/contract drift, `[SEC-01..SEC-10]` for §Security claims, `[RC-005, RC-013]` for §Resiliency/§Architecture claims. Cite the rule ID alongside `[HLD-DRIFT: §<section>]`.
+
+Cite the most specific rule range applicable to the drift (e.g., `[RC-012]` for API changes, `[SEC-01..SEC-10]` for security claims).
+
+For each HLD claim extracted in Phase 1, validate it against code:
+
+- **HLD §Performance** claims (e.g., "p95 < 200ms", "QPS = 10k") — search for benchmarks, load tests, or APM dashboard evidence. If absent, surface as Important: "HLD claims X but no measurement evidence in code/CI."
+- **HLD §Scale** claims (horizontal scaling, vertical scaling, bottlenecks named) — verify deployment config (replicas, autoscaler), connection pools, queue capacities support the claim.
+- **HLD §Security** claims (RBAC, encryption, credential protection) — verify the cited middleware/guard exists and is invoked on the documented surface.
+- **HLD §Resiliency** claims (graceful degradation, circuit breakers, timeouts) — verify cited code paths implement the claim.
+- **HLD §Multi-tenancy** claims (tenant isolation, predictable performance, migration path) — verify query partitioning, RBAC scope, migration tooling.
+- **HLD §Upgrade** claims (backward compat, dependent service order) — verify schema migration policy, API version handling.
+- **HLD §Cost** claims — flag if codebase introduces new cloud resources not reflected in HLD.
+- **LLD §Classes/Interfaces invariants** (thread safety, idempotency, ordering) — search for violations: shared state without locks, non-idempotent retry paths, ordering assumptions broken by concurrency.
+- **LLD §Error Handling policy** — verify retry/backoff/circuit-breaker thresholds in code match the LLD table.
+
+Surface gaps as findings with prefix `[HLD-DRIFT: §<section>]` (Important if the gap is documentation-vs-implementation drift; Critical if the code violates a stated invariant or security claim).
+
+### Phase 4: Identify Actionable Fixes (Spec Generation)
+Instead of mutating the source code, translate all findings into clear, actionable requirements that a developer (or agent) can implement via Test-Driven Development.
+
+### Phase 5: Resilience & Chaos Engineering Assessment
+
+**Applicability note:** Skip categories not applicable to the module type (e.g., network partitions are irrelevant for purely local CLI tools).
+
+> Rule references: `[RC-005]` concurrency & retries, `[SEC-04]` network boundaries, `[CQ-008]` timeouts/cleanup, `[RC-015]` capacity/config bounds. Cite the rule ID in each finding.
+
+Cite relevant rule ranges for resilience findings (e.g., `[RC-005]` for retries, `[CQ-008]` for timeouts).
+
+- **Dependency failure scenarios:** What happens when each external dependency (database, cache, message queue, external API) is unavailable? Are there timeouts, fallbacks, circuit breakers? `[RC-005, CQ-008]`
+- **Timeout analysis:** Are all external calls bounded by timeouts? Are timeout values appropriate (not too long, not too short)?
+- **Disk/resource exhaustion:** What happens when disk fills, memory is exhausted, file descriptors run out?
+- **Clock skew:** Does the module make assumptions about clock synchronization? Are distributed timestamps handled correctly?
+- **Network partitions:** How does the module behave during partial network failures? Split-brain scenarios?
+- **Retry behavior:** Does retry logic use exponential backoff with jitter? Is there a retry budget to prevent retry storms?
+- **Graceful degradation:** Can non-critical features be disabled without affecting core functionality?
+- **Load shedding:** Under extreme load, does the module shed excess requests gracefully?
+- **Capacity/Load Modeling:**
+  - What happens at 10x current traffic? 100x?
+  - Identify bottlenecks: connection pools, thread pools, rate limits, queue depth.
+  - Are there horizontal scaling capabilities?
+  - What is the theoretical maximum throughput?
+- Reference: Netflix Chaos Monkey, Netflix Simian Army, Amazon GameDay.
+
+---
+
+## Update Review History
+
+After completing the review, update `draft/deep-review-history.json`:
+
+```json
+{
+  "reviews": [
+    {
+      "module": "<module-name>",
+      "path": "<module-path>",
+      "timestamp": "<ISO-8601>",
+      "issues_found": <count>,
+      "summary": "<one-line summary>"
+    }
+  ]
+}
+```
+
+Create the file in the `draft/` directory if it does not exist. Append to the `reviews` array if it does. Do NOT save to `.claude/` or `.gemini/`.
+
+---
+
+## Final Report Generation
+
+Output a structured summary and detailed "Implementation Spec" for any needed fixes.
+
+**File to create:** `draft/deep-review-reports/<module-name>.md`
+
+Create the `draft/deep-review-reports/` directory if it does not exist.
+
+**MANDATORY: Include YAML frontmatter with git metadata.** Follow the procedure in `core/shared/git-report-metadata.md` to gather git info and generate the frontmatter. Use `generated_by: "draft:deep-review"` and set `module` to the reviewed module name.
+
+Additional deep-review fields beyond the standard template:
+
+```yaml
+module_path: "<module-path>"
+reviewer: "{model name from runtime}"
+```
+
+**Module reviewed:** name and path
+**Issues by category:** ACID | Resilience | Observability
+**Verdict:** PASS / CONDITIONAL PASS / FAIL
+
+**Verdict criteria:**
+- **FAIL** = any Critical issue found.
+- **CONDITIONAL PASS** = no Critical issues but Important issues exist.
+- **PASS** = only Minor issues or no issues.
+
+Format findings as actionable tasks:
+```markdown
+### [Critical/Important/Minor] Issue Name `[RC-### or CQ-### or SEC-## if applicable]`
+**File:** path/to/file:line
+**Description:** What's wrong conceptually (e.g., Transaction lacks rollback on Exception XYZ).
+**Proposed Fix Specification:**
+- Add `try/except` block catching Exception XYZ.
+- Explicitly call `db.rollback()`.
+- Emit structured log with correlation ID.
+```
+
+Cite the most specific rule ID from `core/guardrails/review-checks.md` (RC-###), `core/guardrails/security.md` (SEC-##), or `core/guardrails/code-quality.md` (CQ-###) that governs the finding. If no numbered rule applies, omit — the finding stands.
+
+**For Phase 3 (Security):** Load `core/guardrails/security.md` and apply the 5-step security reasoning chain. Hard red line violations (SEC-01…SEC-10) are always Critical. Run `core/guardrails/dependency-triage.md` procedure for any dependency manifest files in the module's scope `[RC-014]`.
+
+**Constraints:**
+- Do not refactor code yourself.
+- Flag ambiguous fixes for human review instead of guessing.
+- If the module is too large, decompose it and review sub-modules sequentially.
+
+---
+
+## Pattern Learning
+
+Skip pattern learning if the analysis found zero findings.
+
+After generating the report, execute the pattern learning phase from `core/shared/pattern-learning.md` to update `draft/guardrails.md` with patterns discovered during this module audit. Module-level reviews often reveal architecture and concurrency conventions that are valuable for future analysis.
+
+---
+
+## Report Closing: Next Actions (REQUIRED)
+
+Every deep-review 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> | <author\|on-call\|TBD> | yes/no | `/draft:<skill> <args>` or `n/a` |
+```
+
+Rules:
+- Production-blocking findings (`[SEC-*]`, ACID violations, unbounded resource use) produce blocker rows.
+- Suggest `/draft:adr` for structural changes, `/draft:new-track` for multi-week remediation, `/draft:incident-response` for hot issues, `/draft:tech-debt` for systemic items.
+- Cap at 10 actions; group related fixes under one row.
+
+## Cross-Skill Dispatch
+
+### Suggestions at Completion
+
+After deep-review audit completion:
+
+**If architecture debt found:**
+```
+"Architecture debt identified in module audit. Consider:
+  → /draft:tech-debt — Catalog and prioritize the architecture debt
+  → /draft:adr — Document undiscovered design decisions found during review"
+```
+
+**If documentation gaps found:**
+```
+  → /draft:documentation runbook — Generate operational runbook for this module"
+```
+
+## Mandatory Self-Check (before final report)
+
+Before printing the final report, internally verify and report:
+
+1. **Graph files queried** — JSONL files loaded plus any live graph query-tool invocations (especially `impact` per file in scope).
+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. Source-text scans for API contract strings, secrets, or log audits are exempt.
+
+If `draft/graph/schema.yaml` does not exist, set `Graph files queried: NONE` and use justification `graph data unavailable`.
+
+## Graph Usage Report (append to 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.
+## Skill Telemetry
+
+As the last step after saving the deep-review report, emit a metrics record. Best-effort — never block.
+
+**Payload fields:**
+```json
+{
+  "skill": "deep-review",
+  "module": "<module path or name>",
+  "phases_completed": <N>,
+  "critical_count": <N>,
+  "important_count": <N>,
+  "sec_violations": <N>,
+  "acid_violations": <N>,
+  "graph_queries": <N>,
+  "fallback_grep_count": <N>
+}
+```
+
+**Emit call:**
+```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/emit-skill-metrics.sh" ] && bash "$DRAFT_TOOLS/emit-skill-metrics.sh" \
+  '{"skill":"deep-review","module":"<module>","phases_completed":<N>,"critical_count":<N>,"important_count":<N>,"sec_violations":<N>,"acid_violations":<N>,"graph_queries":<N>,"fallback_grep_count":<N>}'
+```

package/skills/deploy-checklist/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: deploy-checklist
+description: Pre-deployment verification checklist. Generates customized checklists based on tech-stack with rollback triggers. Auto-invoked by /draft:upload.
+---
+
+# Deploy Checklist
+
+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 `scripts/tools/graph-impact.sh --repo . --file <path>` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss.
+2. Run `scripts/tools/cycle-detect.sh --repo .` (and read `draft/graph/architecture.json` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
+3. Load `draft/graph/hotspots.jsonl` — 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:-$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"
+
+"$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 <service>` — Generate checklist for named service
+- `/draft:deploy-checklist track <id>` — Generate from track's change scope
+
+If a track is active: read `draft/tracks/<id>/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/<id>/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/<id>/deploy-checklist.md`
+- Standalone: `draft/deploy-checklist-<timestamp>.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

package/skills/discover/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: discover
+description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
+---
+
+# Discover - Investigation & Quality Router
+
+`/draft:discover` is the single front door for all investigation, auditing, pattern learning, and quality exploration activities.
+
+## When to Use
+
+- Any debugging or root-cause work
+- Code quality reviews (lightweight to exhaustive to architectural)
+- Coverage analysis and test strategy design
+- Discovering and codifying project conventions
+- Monorepo indexing and context aggregation
+- Project tours, impact analysis, or reviewer assistance
+
+## Routing Logic
+
+Strong keyword and phrase matching with fallback to a menu when intent is broad or compound. Several quality commands auto-chain (e.g. review may call bughunt).
+
+| User Intent Keywords                              | Dispatches To            | Purpose |
+|---------------------------------------------------|--------------------------|---------|
+| debug, investigate bug, reproduce, isolate, diagnose | `/draft:debug` | Structured 4-phase debugging |
+| hunt bugs, find bugs, exhaustive sweep, regression hunt | `/draft:bughunt` | 14-dimension bug hunt + regression tests |
+| quick review, fast review, sanity check, lightweight review | `/draft:quick-review` | 4-dimension review (~2 min) |
+| deep review, production audit, module audit, ACID compliance | `/draft:deep-review` | Full module lifecycle + architecture audit |
+| coverage, code coverage, test coverage report | `/draft:coverage` | Coverage measurement and gap report |
+| test strategy, testing plan, coverage targets, pyramid | `/draft:testing-strategy` | Test approach design |
+| learn patterns, discover conventions, update guardrails, anti-patterns | `/draft:learn` | Pattern mining + guardrail evolution |
+| index services, aggregate context, monorepo index | `/draft:index` | Monorepo service context aggregation |
+| tour, walkthrough, onboard me, getting started tour | `/draft:tour` | Guided interactive project tour |
+| blast radius, code impact, affected modules, downstream callers | `/draft:review` or `scripts/tools/graph-impact.sh` | Graph-derived blast-radius before merge |
+| impact, delivery telemetry, track analytics, CDD effectiveness | `/draft:impact` | Project-wide track delivery telemetry |
+| assist review, help reviewer, PR architectural audit | `/draft:assist-review` | Risk audit to support human reviewers |
+
+## Dispatch Examples
+
+User: "debug the flaky test in CI"
+
+→ dispatches to `/draft:debug "flaky test in CI"`
+
+User: "quick review the PR diff"
+
+→ dispatches to `/draft:quick-review [pr context]`
+
+User: "run a deep production audit on the auth service"
+
+→ dispatches to `/draft:deep-review auth`
+
+User: "learn the coding patterns in this repo and tighten guardrails"
+
+→ dispatches to `/draft:learn`
+
+User: "index the monorepo so agents see all services"
+
+→ dispatches to `/draft:index --init-missing`
+
+## Auto-Chains & Recommendations
+
+- `/draft:implement` and `/draft:review` (primary) frequently call into discover skills at phase boundaries.
+- `/draft:discover "full quality"` may suggest or chain review + bughunt + coverage.
+- After major changes, `/draft:discover learn` is recommended to keep guardrails current.
+
+Direct specialist commands are preserved as shims for existing workflows and scripts.