UNPKG

paqad-ai

Version:

Spec-driven development framework — AI agents that think before they type

github.com/Eliyce/paqad-ai

Eliyce/paqad-ai

52 lines (37 loc) • 2.93 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
--- name: spec-quality-review description: 'An optional pre-pass that surfaces spec defects for a human before freeze. Use when a spec was edited and spec freeze has not run, or when a bug suggests the spec contradicts itself.' metadata: model_tier: reasoning cacheable: 'false' output_format: markdown paqad-meta: skill.meta.yaml --- ## What It Does Surfaces likely spec defects (contradictions, formula inconsistencies, boundary gaps, goal conflicts, dangling references, and missing negative cases) as a human-readable list, so an author can fix them before freezing. It is an optional pre-pass, not the gate: `paqad-ai spec freeze` runs the authoritative, deterministic spec-quality review itself and blocks on a critical defect. This skill neither persists a report nor hands anything authoritative downstream. ## Use This When After a spec edit and before you run `paqad-ai spec freeze`, or when an implementation bug suggests the spec may be internally inconsistent, to catch defects early rather than at freeze time. Skipping it changes nothing about the freeze: the freeze runs its own review regardless. ## Inputs - Read the target spec markdown file in full. - Read `references/spec-defect-checklist.md` before issuing findings. - Use `agents/openai.yaml` for the reasoning contract when the workflow executes through agent infrastructure. ## Procedure 1. Run `scripts/scan-defects.sh <spec.md>`: it skips Open Questions and TBD lines and emits candidate hits across the categories in `assets/categories.txt` (vague-quantifier, missing-actor, unbounded-modal, tbd-leak, dangling-ref, goal-collision, no-negative). 2. Confirm each hit (or dismiss with a reason): the script flags candidates, you judge severity. 3. Format a markdown summary per `assets/output.template.md`; validate it with `scripts/lint-output.sh`. 4. Order findings by severity, then by source line. ## Output Contract - Return a `## Findings` section listing active defects with severity, category, location, and the specific clarification or rewrite needed. - Return a `## Resolved` section only when a prior finding is now absent; omit it otherwise. - Persist nothing. This pre-pass writes no `spec-review.json` and no `.paqad/compliance/**` file: the freeze owns the authoritative record (its defect summary is folded into the bundle's `specification.json`). ## Escalate / Stop Conditions - Escalate when the review cannot locate the spec file or the file is not markdown. - Stop short of rewriting the spec; report defects, do not auto-correct them. - This pre-pass never gates the build and never blocks freeze: the freeze's own deterministic review is the blocker. Report findings honestly; do not imply this pass is authoritative. ## Resources - `references/spec-defect-checklist.md` - `scripts/scan-defects.sh` - `scripts/lint-output.sh` - `assets/output.template.md` - `assets/categories.txt` - `agents/openai.yaml`