mattgierhart/PRD-driven-context-engineering / .claude/skills/ghm-gate-check
ghm-gate-check
VerifiedValidates gate criteria before PRD lifecycle advancement by delegating to the readiness scoring pipeline (scripts/readiness.py). Returns a graduated PASS / WARN / BLOCK verdict with top blockers and their causal chain. Triggers before advancing from v0.X to v0.Y or explicit `/ghm-gate-check`.
Gate Check
Validate whether the PRD stage is ready to advance to the next version. Delegates to the three-layer readiness scorer — SoT files → EPICs → stage — then surfaces the leverage view (what to fix first, and which EPICs it unblocks).
Workflow Overview
- Compute → run
scripts/readiness.py run --quietto refreshstatus/readiness.json - Read → parse
status/readiness.json - Report → PASS / WARN / BLOCK verdict with top blockers and causal links
- Recommend → actionable next steps (always highest-leverage first)
Authority
references/gate-criteria.md remains the canonical source of mandatory artifacts per gate. The scorer's GATE_REQUIREMENTS table mirrors it. Do not hand-roll checklists here — the scoring engine is the single source of truth.
Step 1: Compute
Run the orchestrator. It runs SoT → EPIC → stage in dependency order and writes status/readiness.json.
python scripts/readiness.py run --quiet
# exit 0 = all pass, 1 = warn, 2 = block, 3 = error
If the exit code is 3, report a runtime error and stop. If 0/1/2, proceed to Step 2.
Fallback: no scripts available
If scripts/readiness.py is missing or Python is unavailable, fall back to reading status/readiness.json directly. If that's also absent, report: "Readiness not yet computed — install scripts/requirements.txt and run python scripts/readiness.py run."
Step 2: Read
cat status/readiness.json
Extract:
summary.current_stage— the gate being evaluated and its scoresummary.top_blockers— ranked SoT files blocking progressstages.{target}— detailed stage block (dimensions, unmet_criteria, caps)epics.{id}— per-EPIC scores (cite the lowest ones)
Step 3: Report
Use this template. Fill every field from the JSON — do not improvise scores.
## Gate Check Report: {stage.gate_description}
**Verdict**: [PASS | WARN | BLOCK]
**Stage Score**: {stage.score} / 100 (warn < {threshold_warn}, block < {threshold_block})
**Date**: {now}
### Stage Dimensions
| Dimension | Score | Weight |
|-----------|-------|--------|
| required_ids_present | {score} | {weight} |
| relevant_sot_readiness | {score} | {weight} |
| cross_ref_integrity | {score} | {weight} |
| downstream_epic_readiness | {score or "n/a"} | {weight or "—"} |
### Top Blockers (leverage view)
1. **{file}** (score {score}) — blocks {N} EPICs: {EPIC-XX, …} — impact {impact}
2. …
### Unmet Criteria (high severity first)
- [high] {ref}: {reason}
- [medium] {ref}: {reason}
### Recommendation
**If PASS**: Advance to {next_version}. Run `ghm-status-sync` to update the README dashboard.
**If WARN / BLOCK**: Do not advance. Address top blockers in order — fixing the highest-impact SoT file cascades up the graph.
**Next action**: {top_blockers[0] → concrete fix}
Verdict bands
| Stage score | Verdict | Meaning |
|---|---|---|
| ≥ 70 | PASS | Safe to advance |
| 50–69 | WARN | Advance with documented risk; log in PRD change log |
| < 50 | BLOCK | Cannot advance — per rule 05-lifecycle-gates, update the EPIC and STOP |
Step 4: Recommend
Always prioritize by impact = (100 − score) × #EPICs blocked. The top blocker is the single highest-leverage fix; cite its blocking_epics list so the human understands what unblocks.
Quality Gates
- Stage score cited from JSON, not estimated
- Top blockers include their consumer EPICs
- Recommendation is actionable (specific file, specific action)
- Verdict matches the score band exactly (don't round up)
Anti-Patterns
| Pattern | Example | Fix |
|---|---|---|
| Ignoring the score | "Feels ready; pass" | Cite stage.score verbatim |
| Skipping blockers | "Minor stuff, advance anyway" | Block if score < 50; warn if < 70 |
| Hand-rolling criteria | Re-checking IDs manually | Trust the scorer; if wrong, fix GATE_REQUIREMENTS in _readiness/stage.py |
| Forcing PASS | Overriding the verdict | Never override; the score is the contract |
Boundaries
DO:
- Delegate computation to
readiness.py - Cite specific scores, files, and EPICs from the JSON
- Surface the
top_blockersleverage view
DON'T:
- Modify
status/readiness.jsondirectly — it's computed output - Create missing artifacts inside this skill (that's the author's job)
- Override PASS/BLOCK verdicts subjectively
Handoff
After a report:
- PASS: Trigger
ghm-status-sync; the gate advancement updates the README dashboard - WARN: Same as PASS but note the risks in the PRD change log
- BLOCK: Return control to the human. The
top_blockers[0]fix is the single most important next action
References
references/gate-criteria.md— canonical gate requirements (consumed by scorer)references/examples.md— pass/warn/block report examples.claude/rules/07-readiness-protocol.md— the discipline ruledocs/READINESS_PROTOCOL.md— full schema
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |