|
| 1 | +--- |
| 2 | +name: pharaoh-sdd |
| 3 | +description: Use when a developer wants to add a feature, capability, or behaviour change to a project that uses sphinx-needs and a V-model artefact structure, before any requirement or code is written. Triggers on "add a feature", "implement X", "let's build Y", or "do spec-driven development" in a project with .pharaoh/project/ tailoring. |
| 4 | +chains_from: [] |
| 5 | +chains_to: [] |
| 6 | +--- |
| 7 | + |
| 8 | +# pharaoh-sdd |
| 9 | + |
| 10 | +## Overview |
| 11 | + |
| 12 | +The graph is not the hard part. An agent will happily produce one. The hard part is not |
| 13 | +fabricating it. Requirements come from the human, every artefact carries its review, and |
| 14 | +every tier builds clean before the next. This skill enforces that contract. |
| 15 | + |
| 16 | +## Composition |
| 17 | + |
| 18 | +pharaoh-sdd is a non-atomic orchestrator. It does not draft or review artefacts directly. |
| 19 | +It dispatches the following atomic skills: |
| 20 | + |
| 21 | +- `pharaoh-req-draft`: drafts requirement-shaped artefacts at any catalog-declared level |
| 22 | +- `pharaoh-arch-draft`: drafts architecture artefacts |
| 23 | +- `pharaoh-vplan-draft`: drafts verification plans and test cases |
| 24 | +- `pharaoh-req-codelink-annotate`: links implemented code back into the requirement graph |
| 25 | +- `pharaoh-quality-gate`: verifies review coverage and trace completeness at the end |
| 26 | + |
| 27 | +Each `*-draft` skill self-invokes its matching `*-review` as its last step and returns |
| 28 | +`{artefact, review}`. The orchestrator reads that review. It does NOT call `*-review` |
| 29 | +again for a freshly drafted artefact. |
| 30 | + |
| 31 | +## The Iron Gate |
| 32 | + |
| 33 | +Do NOT draft tier N+1 until tier N is drafted, reviewed, validated with `sphinx-build -W`, |
| 34 | +and approved by the human. This holds for every project no matter how small the feature. |
| 35 | + |
| 36 | +Violating the letter of this gate is violating the spirit of it. |
| 37 | + |
| 38 | +## When to use |
| 39 | + |
| 40 | +- A developer asks to add a feature, capability, or behaviour change. |
| 41 | +- The project has `.pharaoh/project/` tailoring and a sphinx-needs V-model. |
| 42 | +- Use even for tiny features. Small features are where requirements get silently invented. |
| 43 | + |
| 44 | +When NOT to use: pure refactors, bug fixes against an existing requirement, or projects |
| 45 | +with no sphinx-needs structure. |
| 46 | + |
| 47 | +## Input |
| 48 | + |
| 49 | +- The developer's feature intent in prose (what, why, measurable success criteria). |
| 50 | +- The project root path. |
| 51 | +- `.pharaoh/project/` tailoring: `artefact-catalog.yaml`, `id-conventions.yaml`, lifecycle |
| 52 | + config, and any domain-specific checklists. |
| 53 | +- `pharaoh.toml` at the project root and `.pharaoh/project/` tailoring (inputs for deriving |
| 54 | + tier order, described in Phase 1 below). |
| 55 | +- `ubproject.toml` at the project root: `[needs.links]` is read from it for the project's |
| 56 | + link-field convention (used in the `normalise` step of the tier loop). |
| 57 | + |
| 58 | +Data-access and strictness concerns are handled by the dispatched atomic skills. pharaoh-sdd |
| 59 | +does not restate them. |
| 60 | + |
| 61 | +## Output |
| 62 | + |
| 63 | +- A set of linked sphinx-needs artefacts forming the V-model graph, one per tier. |
| 64 | +- A clean `sphinx-build -W` after each tier. |
| 65 | +- A pharaoh-quality-gate verdict with review coverage confirmed for every drafted artefact. |
| 66 | + |
| 67 | +## Process |
| 68 | + |
| 69 | +### Phase 0: Elicitation |
| 70 | + |
| 71 | +Before drafting anything. This is a dialogue, not a form. |
| 72 | + |
| 73 | +1. Read project context: `.pharaoh/project/` tailoring (types, tiers, lifecycle), |
| 74 | + `pharaoh.toml`, and a sample of recent needs from the corpus. |
| 75 | +2. Ask the developer clarifying questions ONE at a time: purpose, constraints, success |
| 76 | + criteria, and every parameter value that would otherwise be guessed. |
| 77 | +3. Decompose the feature into individual requirements and present that decomposition. |
| 78 | +4. Gate: the developer approves the requirement list. No invented value survives into |
| 79 | + a requirement. |
| 80 | + |
| 81 | +### Phase 1 onward: walk the V-model tiers |
| 82 | + |
| 83 | +Create a run directory at `.pharaoh/runs/<timestamp>/` before the first tier. Use it for |
| 84 | +all review JSON written during the tier loop. The Terminal step passes this directory to |
| 85 | +`pharaoh-quality-gate`. |
| 86 | + |
| 87 | +Derive the V-model tier order by checking these sources in priority order. First, look for |
| 88 | +an explicit tier or chain declaration in `pharaoh.toml` or `.pharaoh/project/`. If none |
| 89 | +exists, topologically sort the `required_links` chain pairs from the `[pharaoh.traceability]` |
| 90 | +table in `pharaoh.toml` when they cover all tiers in use. If that is still incomplete, infer the order from the |
| 91 | +artefact-catalog types together with the link structure observed in the existing corpus |
| 92 | +(`needs.json`). Present the derived tier order to the developer and get confirmation before |
| 93 | +any drafting begins. |
| 94 | + |
| 95 | +Do not hardcode tier depth. For each tier, in order, run this loop: |
| 96 | + |
| 97 | +| step | action | |
| 98 | +|------|--------| |
| 99 | +| draft | Dispatch the tier's atomic draft skill once per artefact. The draft skill self-invokes its review and returns `{artefact, review}`. | |
| 100 | +| evaluate | Read the attached review. If `overall: fail`, `overall: needs_work`, or any binary axis has `score: 0`, re-dispatch the draft skill with the review action items folded into the description. Use `pharaoh-req-regenerate` for requirements, re-invoke the draft skill directly for arch and vplan. | |
| 101 | +| normalise | If the project traces with a generic link field (read from `ubproject.toml [needs.links]` and the existing corpus), rewrite the drafted directive's typed link option (`:satisfies:` or `:verifies:`) to that field. If `ubproject.toml` is absent or has no `[needs.links]` table, keep the typed link as-is. | |
| 102 | +| persist | Write the artefact into the docs tree. Write the review JSON into the run directory using the filename convention `<id>_review.json` (for req-review), `<id>_arch_review.json` (for arch-review), and `<id>_vplan_review.json` (for vplan-review). These names are matched by `pharaoh-self-review-coverage-check`. | |
| 103 | +| rebuild | Run `sphinx-build -W` on the docs. The tier is not done until the build is clean and `needs.json` regenerates with the new needs. The `needs.json` output location is the project's configured path, resolvable from `conf.py` or `ubproject.toml` (on a typical demo it is `docs/_build/html/needs.json`). | |
| 104 | +| checkpoint | Present the tier's artefacts to the developer. Get approval before the next tier. | |
| 105 | + |
| 106 | +At the implementation tier the agent writes the code directly, following test-driven |
| 107 | +development practice (write the failing test first, then make it pass, then refactor). No |
| 108 | +Pharaoh atomic skill governs this tier. Once the implementation is complete, run |
| 109 | +`pharaoh-req-codelink-annotate` with `file_path`, `anchor`, `project_root`, and `mode` |
| 110 | +supplied to link the finished code back into the requirement graph. After annotation, run |
| 111 | +`sphinx-build -W` to confirm the build is clean with the code links in place. Present the |
| 112 | +completed implementation and annotation to the developer and get approval before proceeding |
| 113 | +to the Terminal step. |
| 114 | + |
| 115 | +### Terminal |
| 116 | + |
| 117 | +Run `pharaoh-quality-gate` passing `project_root` and the run directory (via |
| 118 | +`gate_spec.invariants.self_review_coverage`). The `self_review_coverage` invariant reads the |
| 119 | +run directory directly and confirms every drafted artefact has a matching review JSON on |
| 120 | +disk. `artefacts_summary_path` is optional and may be omitted here because the pharaoh-sdd |
| 121 | +chain runs draft-and-review per tier but does not run `pharaoh-mece` or |
| 122 | +`pharaoh-coverage-gap`. The deliverable is a V-model graph where every tier traces to the |
| 123 | +next, every artefact has a review on disk, and the build is clean. |
| 124 | + |
| 125 | +## The baseline this skill exists to stop |
| 126 | + |
| 127 | +Handed "add feature X, do spec-driven development" without this skill, an agent will: |
| 128 | + |
| 129 | +- Invent the requirements itself, with fabricated thresholds, parameters, and acceptance |
| 130 | + criteria, instead of eliciting them from the developer. |
| 131 | +- Run requirement, design, test, and code in one unattended pass with no human in the loop. |
| 132 | +- Draft every artefact and review none. |
| 133 | +- Build once at the end without `-W`, accepting warnings silently. |
| 134 | + |
| 135 | +Each of those is a defect. The process above closes them. |
| 136 | + |
| 137 | +## Rationalisations: STOP |
| 138 | + |
| 139 | +| Excuse | Reality | |
| 140 | +|--------|---------| |
| 141 | +| "I can infer the parameters myself." | An inferred parameter is a fabricated requirement. Elicit it. | |
| 142 | +| "The build succeeded, it is fine." | A build without `-W` passes on warnings. Run `-W`. | |
| 143 | +| "The draft already passed, skip the review." | The draft skill attaches a review. Read it. `overall: needs_work` triggers a re-dispatch just as `fail` does. | |
| 144 | +| "It is a small feature, skip the gate." | Small features are where requirements get invented. The gate holds. | |
| 145 | +| "Running the whole chain is faster." | An unattended chain bakes in decisions the developer never approved. Stop at every checkpoint. | |
| 146 | + |
| 147 | +## Red flags: STOP and return to the last passed gate |
| 148 | + |
| 149 | +- About to write a requirement value the developer never gave you. |
| 150 | +- About to draft tier N+1 while tier N has a `fail`, `needs_work`, or `score: 0` review. |
| 151 | +- About to move past a tier with `sphinx-build` warnings. |
| 152 | +- Ran draft, design, and test with no human pause between them. |
0 commit comments