Feature Specification: FEAT-008 — Artifact Template Quality and Completeness
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
01-frame/features/FEAT-008-artifact-template-quality.md):
ddx:
id: FEAT-008
authoring:
home: repo
depends_on:
- helix.prd
- FEAT-006
review:
self_hash: 55c3f5b337e66301e666cdb14967f0ecee4d9eaffae50aa774a44b4ba343a3fd
deps:
FEAT-006: 1711c08bf5e041cd041c762594f278d35744351d4a25b8251566de2dd778abd3
FEAT-016: 226872932728d635279abac06206be77cee1075d787aae7760010941adb9c1e1
helix.prd: 2b22383538b33c6ecee57f43d85128dfef7d56254766b757aa36439e35f2bfc9
reviewed_at: "2026-05-25T23:05:20Z"Feature Specification: FEAT-008 — Artifact Template Quality and Completeness
Feature ID: FEAT-008 Status: Draft Priority: P1 Owner: HELIX maintainers
Overview
HELIX artifact templates (Vision, PRD, Feature Spec, Solution Design, Technical Design, ADR, Test Plan) should be self-documenting and machine-interpretable. Each template must include clear instructions, agent-oriented generation prompts, review checklists, and relationship declarations that allow the artifact graph to be constructed automatically.
Problem Statement
- Current situation: Templates exist under
.ddx/plugins/helix/workflows/activities/*/artifacts/*/template.mdbut vary in completeness. Some include generation prompts, others don’t. Review checklists are absent. Relationship declarations are embedded in meta.yml but not surfaced to agents or reviewers. - Pain points:
- Agents produce artifacts with missing or weak sections because templates don’t explain what belongs in each section.
- Adversarial review has no structured checklist, so reviewers apply inconsistent criteria.
- The artifact graph (Vision → PRD → Specs → Designs → Tests) cannot be constructed automatically because relationship declarations are inconsistent across templates.
- New HELIX users don’t know what a “good” artifact looks like because templates lack examples.
Functional Requirements
FR-1: Section Instructions
Each artifact template must include a brief instruction block (HTML comment or frontmatter annotation) for every section, explaining what belongs there and what does not.
FR-2: Generation Prompts
Each artifact template must include or reference a generation prompt that agents can use to draft the artifact from higher-level governing artifacts. The prompt must specify which upstream artifacts to read and what context to synthesize.
FR-3: Review Checklists
Each artifact template must include a review checklist that adversarial review agents use to evaluate the artifact. The checklist must be specific to the artifact type (e.g., “Does every P0 requirement have a testable acceptance sketch?” rather than generic “Is this complete?”).
FR-4: Relationship Declarations
Each artifact template must declare its upstream dependencies and downstream
artifacts in a machine-readable format (frontmatter depends_on and
enables fields), so the artifact graph can be traversed programmatically.
FR-5: Exemplar Artifacts
Each artifact type must include at least one exemplar — a fully worked example of a well-written artifact — either inline in the template or as a companion file. Exemplars should be drawn from real HELIX projects where possible.
FR-6: AC↔Test Traceability Is a Template Requirement
Templates must bake in acceptance-criteria-to-test traceability so that coverage is mechanically checkable rather than asserted in prose:
Stable AC IDs: user-story acceptance criteria carry stable identifiers of the form
US-<n>-AC<m>(e.g.US-001-AC1). The ID survives edits so downstream artifacts and tests can reference a specific criterion by name.Given/When/Then shape: every acceptance criterion is a single Given/When/Then, one precondition, one action, one observable outcome — compound criteria are split.
Story-level mapping matrix: the story test plan owns the per-criterion matrix that maps each
US-<n>-AC<m>to the failing test(s) that prove it, keyed by the stable AC ID. The test-plan template does not duplicate this matrix — it aggregates strategy and allocates criteria to test layers (contract / integration / unit / E2E).Layer allocation: the aggregating test plan records which layer verifies each criterion class, so reviewers can see that no P0 criterion is unallocated.
Behavior-based test names: names identify the behavior and relevant condition or rejection branch using the project’s framework conventions. Stable requirement citations remain in test source; names alone do not establish coverage. Existing canonical citations in names remain valid.
Observed results without duplicate records: completion connects the existing mapping and test-source citations to actual results for the tested revision. Normal test/CI reports suffice when they capture the required behavior and provenance. Supplemental observations are linked from the existing mapping only where the normal reporting path leaves a proof gap; no shared evidence file or second per-criterion matrix is required.
This requirement complements the honesty property in [[FEAT-016]]: stable AC IDs let the claims-vs-reality check resolve “this criterion is covered by test X” against a specific, named referent rather than against prose.
Note: template-conformance (FR-1..FR-5) catches missing or weak sections. It does not catch a well-formed artifact that asserts an untrue claim (a phantom test, an invented coverage figure). That honesty property is governed by [[FEAT-016]] — Artifact Honesty (Claims-vs-Reality).
FR-7: Decomposition Coverage (Story-per-FR, ADR-per-decision)
Templates bake in decomposition expectations so rigor is reproducible rather than left to runtime taste:
- Story per functional requirement: PRD functional requirements carry stable
FR-nIDs and everyFR-nmaps to ≥1 user storyUS-n. A story may cover severalFR-ns but should not bundle unrelated requirements without recorded justification. The FR→story mapping is a coverage floor, enforced as a blocking gap by reconcile-alignment (Acceptance Criteria Validation) — extra stories are always welcome; only aFR-nwith no story is a finding. - ADR per material decision: a material architecture/technology decision should be recorded in an ADR. This is an expectation, not a hard gate — “material” is too fuzzy to gate deterministically, so reviewers surface a missing ADR as a recommendation rather than a blocking failure.
This is a floor on minimum rigor (decomposition + traceability), not a cap and not a promise of equal total depth across runtimes.
FR-8: Interface-Quality Guidelines and the DESIGN.md Artifact
Templates and concern practices must govern interface-quality so a UI is built with a legible, consistent design system rather than left to runtime taste:
- Required visual cues (
ux-radix): the current page MUST show a visible active state andaria-current="page"on the active nav item; interactive elements express their states where applicable (hover + focus-visible for enabled controls; disabled where disablement exists; loading for async actions; empty/error for data/form/content surfaces).aria-currentis both a UX and an accessibility cue — keep it consistent witha11y-wcag-aa. - The DESIGN.md artifact: a governed, project-level artifact
(
workflows/activities/02-design/artifacts/design-system/, outputdocs/helix/02-design/DESIGN.md) captures the app’s concrete interface-system decisions — navigation model + active-state convention, visual hierarchy, the applicable interaction states, and tokens (color/spacing/type). It is the app-specific instance of these guidelines, not a mirror of the concern library, and explicitly excludes runtime architecture, data flow, component implementation internals, and ADR material (those live in architecture/solution-design/ADRs). - Mechanized visual-cue verification: a UI web app’s browser e2e MUST assert
aria-current="page"on the active nav item for ≥1 route (required, non-optional). An active class/style may be asserted additionally but is never a substitute foraria-current; no pixel/screenshot assertions for this gate. This makes “does it show me where I am?” a checkable gate that feeds theverificationconcern.
Non-Functional Requirements
NFR-1: Template Size
Templates including instructions and checklists must remain under 200 lines to avoid overwhelming agents with boilerplate.
NFR-2: Backward Compatibility
Existing artifacts must remain valid. New template features are additive.
Acceptance Criteria
- Every artifact template under
workflows/activities/*/artifacts/*/template.mdincludes section instructions, a generation prompt reference, and a review checklist. - Every artifact template declares
depends_onandenablesrelationships in its meta.yml. - At least one exemplar artifact exists for each artifact type.
/helix reviewcan load the review checklist for the artifact type being reviewed and evaluate against it.- User-story acceptance criteria carry stable
US-<n>-AC<m>IDs in Given/When/Then form; the story test plan maps each AC ID to concrete failing tests; the project test plan aggregates strategy and allocates criteria to test layers without duplicating the story-level matrix. - The
ux-radixpractices require current-location feedback (visible active state +aria-current="page") and the where-applicable interaction states; a governeddesign-systemartifact (DESIGN.md) exists with the non-goal section excluding architecture/data-flow/impl-internals/ADR material; and a UI web app’s browser e2e assertsaria-current="page"on the active nav for ≥1 route (required, never substituted by a class/style or screenshot assertion).
Constraints
- Templates must work with the existing DDX artifact management system.
- Relationship declarations must be compatible with the existing
ddxfrontmatter format.
Out of Scope
- Automated artifact graph visualization (future work).
- Enforcing template compliance at write time (advisory only for now).
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/features/FEAT-008-artifact-template-quality.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:418b6374…bde6dd18
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/features/FEAT-008-artifact-template-quality/",
"digest": {
"alg": "sha256",
"value": "418b6374511dd1d4d6c61074b26f1c34b4acd05f01af3d0160848778bde6dd18"
}
}
],
"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": "vR9-RxowZTPDE4leWnDkrDJJ4EQQqpTUW0WLjdTR3IFogoq6NLOi4_jncdIAGJl8BTL0lW6Kvz0hexyvsETzBg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}