spec-technical-review

Spec technical review

Resolve all engineering decisions that block the implementation plan. Do not implement. Produce a Technical Design Document (TDD) and draft ADRs.

Runs while the Draft spec PR is open — write TDD and ADR files locally and emit Forge readiness for the spec branch. Gate 2 label remains spec-pending. PE architecture acceptance is recorded in artifact metadata (Draft → Accepted); spec-lgtm is set only after the full spec package (including plan) is on head.

Benchmarked against: Stripe/Cloudflare/Oxide RFC process, Sentry design-first gate, agentic_development_workflow multi-role review, GitHub Spec Kit /speckit.plan architectural artifact pattern.

NON-NEGOTIABLE

1. Never skip a check in references/checks.md. Mark SKIPPED with reason.
2. Every engineering decision in the output must be resolved (recommendation recorded) or explicitly deferred with a named risk and default assumption.
3. Do not ask PM to choose architecture. Route only product-scope and user-visible behaviour questions to the meta PRD PR. See references/governance.md for the routing rubric.
4. Every NEW-ADR from feasibility maps to exactly one disposition: ADR_REQUIRED with a Draft file under adr_dir, TDD_ONLY with rationale, or DEFERRED_WITH_DEFAULT with risk and revisit trigger.
5. Dual output: chat summary + saved TDD file (local persistence + Forge readiness).
6. Run T0–T5 control loop (Gather → Understand → Analyze → Design → Execute → Verify).
7. Human PE acceptance is required before the implementation plan runs. Technical review creates Draft ADR files first; planning consumes only Accepted files in {adr_dir}. Mid-lane PE work updates files on the spec branch — it does not set spec-lgtm.
8. Verify light freshness: product-spec H1–H3 citations, tip continuity, and G1 when applicable agree with live handoff. Stop on authority drift. Do not fail closed solely on feasibility artifact.digest mismatch — feas/TDD digests are walk-time (PURGE at initiative closure).
9. Product/architecture boundary. PE may frame options and draft ADRs against approved REQ-* constraints. An ADR must not become Accepted when it depends on user-visible behavior not already represented by an approved REQ-* — amend and re-approve the spec first. Reference REQ-* by id only in Context/Recommendation/Consequences — never quote or paraphrase the REQ's behavioral sentence; that restates the feature instead of stating the engineering decision. T12 enforces this as an independent re-read pass, not a same-pass self-grade (see references/checks.md).
10. No forge mutations. Do not commit, push, branch, open PRs, apply labels, create issues, or merge. Fill handoff.forge / recommend /commit-workspace.
11. Ground every NEW-ADR finding in the actual codebase before classifying or drafting it — never draft from feasibility's ALTERNATIVE: text alone. Feasibility's F1/F2 baseline already inspected the repo once; this stage re-verifies and extends that evidence, because a finding's prose can itself encode a wrong question (see the ADR qualification rubric below). Use a codegraph provider when available (prayog-skills/references/codegraph-tool-contract.md), otherwise read source_roots directly — the tool is optional, the grounding activity is not. Record what was found (or "none found — new capability") in the row's Code evidence — extend feasibility's column, don't just trust it blank or stale.
12. If a codegraph provider is available, prefer it for the grounding pass in NON-NEGOTIABLE 11 and for other architecture/impact questions. Always fall back to direct source_roots reads when unavailable — never block or change outcome selection on its absence.