Desired-state authoring: goal and approach
Example from HELIX’s own docs. This generated page comes from
docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.
Source identity (from
02-design/design-desired-state-authoring.md):
ddx:
id: helix.design.desired-state-authoring
authoring:
home: repo
links:
- helix.prd
- helix.principlesDesired-state authoring: goal and approach
Scope and assumptions
HELIX documents define the intended system and the reasons for consequential choices. A useful specification is complete before its implementation exists. Execution status belongs to the runtime work tracker. Repository history belongs to source control; HELIX documents contain no pull-request numbers, repository revision identifiers, or delivery-history citations.
Technical Approach
Each sentence contributes a requirement, decision, action, explanation, or necessary example. Use canonical terms and name the actor. Put conditions before actions and give each procedural step one principal action. Preserve obligation, permission, uncertainty, and exceptions. This is plain technical English, not a claim of compliance with a controlled-language standard.
Ordinary authoring reads the target and the authorities needed to resolve the requested change. Follow a relationship only when its content can affect that change. Align compares the affected documents; implementation assessment is an explicit, scoped audit. An accepted decision establishes direction, not a claim that the decision has been implemented.
Architecture and contracts state the operative choices. ADRs retain significant rationale, with obsolete decisions excluded from routine context. Templates require only content necessary to understand and use the artifact. Optional sections can be omitted without N/A entries. Reviews do not automatically create new gates, documents, work items, or machine-readable reports.
Factual reports still need evidence such as measurements, test results, and observations. They do not maintain a second execution ledger. Release versions identify distributions; database transaction semantics remain technical content.
Component Behavior
| Component | Required behavior |
|---|---|
| Routing skill and workflow contracts | Bound context reads and follow-up actions to the request; preserve explicit audits |
| Artifact catalog | Describe desired outcomes and relevant rationale without delivery bookkeeping |
| Project documents and shared guidance | Apply the same distinction between intent, observations, and execution status |
| Validators and evaluation fixtures | Check useful requirements and requested output shapes, not mandatory ceremony |
Design Rules
- Keep template structure in templates, authoring instructions in prompts, and review criteria in metadata.
- Retain repetition only when a consumer would otherwise miss a necessary rule.
- Preserve artifact identities and technical requirements.
- Moving text into mandatory references is not a reduction. Shorter output is useful only when requirements, exceptions, and evidence remain clear.
Acceptance Criteria
- A small requirement edit consults relevant authorities and stops after the requested coherent change; unrelated ADRs require no implementation audit.
- An accepted, unimplemented decision is a valid specification.
- An explicit implementation audit reports missing behavior without weakening the specification or inserting implementation status into it.
- Conversational review needs no machine report; a requested structured report remains available to runtimes and evaluation consumers.
- Active documents and catalog examples contain no repository-history citations; transaction terminology, release versions, and content digests remain valid.
- Narrow, complex, missing-prerequisite, and conflicting-authority scenarios each produce the shortest output that keeps requirements, exceptions, and evidence clear.
Risks
Older action procedures and evaluation fixtures can silently reinstate removed requirements. Reconcile them with the mode contracts. Broad text replacement can damage technical meaning; inspect matches before changing them.
Migration & Rollback
Keep artifact paths and identifiers stable. Regenerate derived catalog pages from their source files. If behavior regresses, restore the affected rule and its focused check without reinstating unrelated bookkeeping.
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
artifacts/design-desired-state-authoring.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:52fb33ff…a0423778
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/artifacts/design-desired-state-authoring/",
"digest": {
"alg": "sha256",
"value": "52fb33ffb04f2752faff6cdef4c3a6f32a95c439e0394355cf1dc0d8a0423778"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "LHHReaPgqUeC3DJcT-MD_bWbhacL6NJxIls3GgdP5RxwJqNIODKr8vtdq20PxYczKeEjbFjQTKhLsWzqtZ3eDg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}