| name | pharaoh-sdd |
| 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. |
| chains_from | [] |
| chains_to | [] |
pharaoh-sdd
Overview
The graph is not the hard part. An agent will happily produce one. The hard part is not
fabricating it. Requirements come from the human, every artefact carries its review, and
every tier builds clean before the next. This skill enforces that contract.
Composition
pharaoh-sdd is a non-atomic orchestrator. It does not draft or review artefacts directly.
It dispatches the following atomic skills:
pharaoh-req-draft: drafts requirement-shaped artefacts at any catalog-declared levelpharaoh-arch-draft: drafts architecture artefactspharaoh-vplan-draft: drafts verification plans and test casespharaoh-req-codelink-annotate: links implemented code back into the requirement graphpharaoh-quality-gate: verifies review coverage and trace completeness at the end
Each *-draft skill self-invokes its matching *-review as its last step and returns
{artefact, review}. The orchestrator reads that review. It does NOT call *-review
again for a freshly drafted artefact.
The Iron Gate
Do NOT draft tier N+1 until tier N is drafted, reviewed, validated with sphinx-build -W,
and approved by the human. This holds for every project no matter how small the feature.
Violating the letter of this gate is violating the spirit of it.
When to use
- A developer asks to add a feature, capability, or behaviour change.
- The project has
.pharaoh/project/ tailoring and a sphinx-needs V-model.
- Use even for tiny features. Small features are where requirements get silently invented.
When NOT to use: pure refactors, bug fixes against an existing requirement, or projects
with no sphinx-needs structure.
Input
- The developer's feature intent in prose (what, why, measurable success criteria).
- The project root path.
.pharaoh/project/ tailoring: artefact-catalog.yaml, id-conventions.yaml, lifecycle
config, and any domain-specific checklists.pharaoh.toml at the project root and .pharaoh/project/ tailoring (inputs for deriving
tier order, described in Phase 1 below).ubproject.toml at the project root: [needs.links] is read from it for the project's
link-field convention (used in the normalise step of the tier loop).
Data-access and strictness concerns are handled by the dispatched atomic skills. pharaoh-sdd
does not restate them.
Output
- A set of linked sphinx-needs artefacts forming the V-model graph, one per tier.
- A clean
sphinx-build -W after each tier.
- A pharaoh-quality-gate verdict with review coverage confirmed for every drafted artefact.
Process
Phase 0: Elicitation
Before drafting anything. This is a dialogue, not a form.
- Read project context:
.pharaoh/project/ tailoring (types, tiers, lifecycle),
pharaoh.toml, and a sample of recent needs from the corpus.
- Ask the developer clarifying questions ONE at a time: purpose, constraints, success
criteria, and every parameter value that would otherwise be guessed.
- Decompose the feature into individual requirements and present that decomposition.
- Gate: the developer approves the requirement list. No invented value survives into
a requirement.
Phase 1 onward: walk the V-model tiers
Create a run directory at .pharaoh/runs/<timestamp>/ before the first tier. Use it for
all review JSON written during the tier loop. The Terminal step passes this directory to
pharaoh-quality-gate.
Derive the V-model tier order by checking these sources in priority order. First, look for
an explicit tier or chain declaration in pharaoh.toml or .pharaoh/project/. If none
exists, topologically sort the required_links chain pairs from the [pharaoh.traceability]
table in pharaoh.toml when they cover all tiers in use. If that is still incomplete, infer the order from the
artefact-catalog types together with the link structure observed in the existing corpus
(needs.json). Present the derived tier order to the developer and get confirmation before
any drafting begins.
Do not hardcode tier depth. For each tier, in order, run this loop:
| step | action |
|---|
| draft | Dispatch the tier's atomic draft skill once per artefact. The draft skill self-invokes its review and returns {artefact, review}. |
| 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. |
| 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. |
| 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. |
| 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). |
| checkpoint | Present the tier's artefacts to the developer. Get approval before the next tier. |
At the implementation tier the agent writes the code directly, following test-driven
development practice (write the failing test first, then make it pass, then refactor). No
Pharaoh atomic skill governs this tier. Once the implementation is complete, run
pharaoh-req-codelink-annotate with file_path, anchor, project_root, and mode
supplied to link the finished code back into the requirement graph. After annotation, run
sphinx-build -W to confirm the build is clean with the code links in place. Present the
completed implementation and annotation to the developer and get approval before proceeding
to the Terminal step.
Terminal
Run pharaoh-quality-gate passing project_root and the run directory (via
gate_spec.invariants.self_review_coverage). The self_review_coverage invariant reads the
run directory directly and confirms every drafted artefact has a matching review JSON on
disk. artefacts_summary_path is optional and may be omitted here because the pharaoh-sdd
chain runs draft-and-review per tier but does not run pharaoh-mece or
pharaoh-coverage-gap. The deliverable is a V-model graph where every tier traces to the
next, every artefact has a review on disk, and the build is clean.
The baseline this skill exists to stop
Handed "add feature X, do spec-driven development" without this skill, an agent will:
- Invent the requirements itself, with fabricated thresholds, parameters, and acceptance
criteria, instead of eliciting them from the developer.
- Run requirement, design, test, and code in one unattended pass with no human in the loop.
- Draft every artefact and review none.
- Build once at the end without
-W, accepting warnings silently.
Each of those is a defect. The process above closes them.
Rationalisations: STOP
| Excuse | Reality |
|---|
| "I can infer the parameters myself." | An inferred parameter is a fabricated requirement. Elicit it. |
| "The build succeeded, it is fine." | A build without -W passes on warnings. Run -W. |
| "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. |
| "It is a small feature, skip the gate." | Small features are where requirements get invented. The gate holds. |
| "Running the whole chain is faster." | An unattended chain bakes in decisions the developer never approved. Stop at every checkpoint. |
Red flags: STOP and return to the last passed gate
- About to write a requirement value the developer never gave you.
- About to draft tier N+1 while tier N has a
fail, needs_work, or score: 0 review.
- About to move past a tier with
sphinx-build warnings.
- Ran draft, design, and test with no human pause between them.
