Skip to content

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.principles

Desired-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

ComponentRequired behavior
Routing skill and workflow contractsBound context reads and follow-up actions to the request; preserve explicit audits
Artifact catalogDescribe desired outcomes and relevant rationale without delivery bookkeeping
Project documents and shared guidanceApply the same distinction between intent, observations, and execution status
Validators and evaluation fixturesCheck 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"
    }
  ]
}