Developer orientation pilot
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
06-iterate/developer-orientation-pilot.md):
ddx:
id: helix.developer-orientation-pilot
status: draft
authoring:
home: repoDeveloper orientation pilot
Scope and completion conditions
Create HELIX’s solution overview, developer guide, and one end-to-end architecture walkthrough. Use repository evidence to improve reusable catalog types without introducing duplicate structural authority. Complete when the instances and examples exist, entrypoints link them, graph/reference publication is regenerated, and repository gates have recorded outcomes.
Plan
- Trace current routing, catalog, packaging, and validation sources.
- Write the overview and guide; attach the authoring walkthrough to Architecture.
- Extract two artifact types and optional walkthrough guidance from the pilot.
- Regenerate derived content; validate type shape, instances, and full suite.
Findings and template changes
| Pilot finding | Reusable change |
|---|---|
| Architecture is long and mixes introductory and detailed reference material | Solution Overview supplies a concise system map and reading path with explicit authority links |
| Existing contributor instructions referred to obsolete skill/release surfaces | Developer Guide requires source-backed commands, generated-output recipes, expected results, and a maintained contributor entrypoint |
| HELIX is content plus a skill; a service-centric diagram would misrepresent it | Diagram prompts require actual actors/content, labeled interactions, and a legend |
| Static validators do not establish live model behavior | Walkthrough steps name evidence and verification limits |
| A repository-reading author cannot establish newcomer success | Guide requires an observed trial or explicit pending status |
Boundaries and follow-up
The walkthrough is an adjacent architecture explanation, not a third new type. Overview and guide remain drafts until human review. No unfamiliar-developer trial has occurred; a future trial should record environment, first task, help needed, observed result, and blockers. No live model, deployment, or release is part of this pilot.
Verification and continuation
Completed: three pilot documents, two four-file catalog types, optional walkthrough guidance, contributor links, generated graph, reference pages, and published project artifacts.
python3 scripts/helix_validate_artifact_meta.py: 57 types pass.- Instance validator: Solution Overview and Developer Guide pass with zero findings.
- New instance Markdown links: all relative targets exist.
just test: passes. The deck lane initially skipped missingpptxgenjs; rerunningjust test-deck-renderwith the bundled Node dependency succeeds, including geometry checks and rasterizing 12 slides. The optional PowerPoint validator skips because the chosen Python lackslxml/defusedxml.- Innsigle lane skips because its CLI is unavailable and package access is restricted. Headline source byte comparison skips an absent external checkout.
- Hugo production-base-path build: passes.
python3 scripts/check-website-links.py: 65,576 links/images resolve across 391 pages.lefthook run pre-commit: passes; its advisory revalidation script reports a missing historical path and is configured nonblocking.git diff --check: passes.
The default Python lacks PyYAML. Validation used an existing cached PyYAML
installation via PYTHONPATH; the guide now includes dependency recovery.
No unfamiliar-developer trial has occurred. Remaining evaluation is human review
of the drafts and a real newcomer first-contribution session. No release or
remote publication was performed.
Reversal (2026-10-20)
The Developer Guide type is retired. The guide’s developer audience
(workflows/publish/audiences/developer.yml) already names a developer-guide
page with the same reader task, in a voice written for people, checked against
its sources, and reviewed by a second reader; a governed type for the same page
was a second home for one document. HELIX’s own developer guide moved to
docs/guide/developer/developer-guide.md as an adopted guide page. Solution
Overview stays a governed type: it is the explanation the developer pages are
built from.
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/developer-orientation-pilot.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:75d0ebf1…af25ab28
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/developer-orientation-pilot/",
"digest": {
"alg": "sha256",
"value": "75d0ebf1e354f0e13f1c8e7a184a708dd147d337c0b115cfb3a1c377af25ab28"
}
}
],
"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": "ihbceN6E6BhkpgY16nE3b9V_M8gncD7HnyzuaxLqD0XGGDALsmVZZ9KrBkM2F4zB_S1s66FH2bVZLVtraPTdDQ",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}