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 spec PR is open — commit TDD to the spec branch. PE sign-off is a GitHub Approve on the spec PR (CODEOWNERS on Technical-Review-*).

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](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.

1. 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](references/governance.md) for the routing rubric.

1. Every NEW-ADR from the feasibility report must map to a draft ADR or

an explicit defer entry in this document.

1. Dual output: chat summary + saved TDD file committed to spec branch.
2. Run T0–T5 control loop (Gather → Understand → Analyze → Design → Execute → Verify).
3. Human PE sign-off is required before the implementation plan runs — PE

Approve on the spec PR, not a separate merge gate after spec merge.

Inputs

Resolve paths from .harness/profile.yaml or [references/layout-defaults.md](references/layout-defaults.md).

1. Feasibility report — primary input (REQUIRED); source of NEW-ADR

findings, Critical/Should-fix items, open engineering questions

1. Initiative spec — (REQUIRED)
2. ADR directory — existing accepted ADRs from adr_dir (REQUIRED)
3. rules_glob — workspace MDC rules (REQUIRED). Read before T2 Analyze.
4. As-built — implementation-status.md (REQUIRED)
5. .harness/profile.yaml or layout defaults (REQUIRED)

When to use

• Feasibility report contains one or more NEW-ADR findings
• Feasibility has Critical findings involving module design, interface shape,

or test policy

• Implementation plan is blocked by engineering questions (not PM questions)
• PE wants to document interface contracts before planning

Process

1. T0 Gather — feasibility report, spec, ADRs, rules_glob, as-built
2. T1 Understand — list all NEW-ADR items, Critical/Should-fix engineering

findings, and open engineering questions from feasibility

1. T2 Analyze — read relevant Accepted ADRs; read rules_glob; map each

finding to an engineering decision, a PM question, or a domain clarification (routing rubric in [references/governance.md](references/governance.md))

1. T3 Design — for each engineering decision: state options, state

recommended choice with rationale, write draft ADR if required; produce module boundary diagram; specify public interface contracts

1. T4 Execute — write TDD; run T1–T10 checks; commit to spec branch
2. T5 Verify — all engineering blockers resolved or deferred with defaults;

only genuine PM/domain questions remain outstanding (routed to meta PRD PR)

Output

Save to {reports_dir}/Technical-Review-{initiative}.md (from profile).

Use [references/output-template.md](references/output-template.md).

PE sign-off

Commit TDD to the spec PR branch. PE reviews on the same spec PR:

• Discuss engineering decisions in spec PR comments
• Submit GitHub Approve when T1–T10 checks pass
• CODEOWNERS on Technical-Review-* enforces PE as required reviewer

After PE approves, dev runs /spec-implementation-plan on the same branch.

Routing rubric

See [references/governance.md](references/governance.md) for the full table.

Quick rule:

• Engineering — module boundaries, interface contracts, ADR gaps, test

policy, error propagation, observability, data contract ownership → PE resolves on spec PR

• Product — user-visible behaviour choices, scope cuts, priority → meta PRD PR
• Domain — business source-of-truth (tab names, BU process, data ownership)

→ named domain SME

• Auto-fixable — naming drift, enum value mismatches with spec → agent fixes

without human, note in TDD

Draft ADR format

For each NEW-ADR finding, produce a draft section (not a file during PE review). After PE Approve, /spec-implementation-plan must include a pre-W0 TASK-SPEC-ADR-NN that promotes each TDD §4 draft to {adr_dir}/adr-NNN-{slug}.md with status Accepted, PE name, and date. Manual promotion by PE or human is a valid fallback if the plan has not run yet.

### Draft ADR — {short title}
**Status:** Draft (requires PE sign-off)
**Problem:** …
**Options considered:**
  A. … (pros / cons)
  B. … (pros / cons)
**Recommendation:** Option A — {one-sentence rationale}
**Consequences:** …
**Open for review by:** {PE name or "PE checkpoint"}

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drivestream-lab
• Source: drivestream-lab/prayog-skills
• License: MIT

Install and usage instructions live in the source repository linked above.