Skip to content

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: repo

Developer 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

  1. Trace current routing, catalog, packaging, and validation sources.
  2. Write the overview and guide; attach the authoring walkthrough to Architecture.
  3. Extract two artifact types and optional walkthrough guidance from the pilot.
  4. Regenerate derived content; validate type shape, instances, and full suite.

Findings and template changes

Pilot findingReusable change
Architecture is long and mixes introductory and detailed reference materialSolution Overview supplies a concise system map and reading path with explicit authority links
Existing contributor instructions referred to obsolete skill/release surfacesDeveloper 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 itDiagram prompts require actual actors/content, labeled interactions, and a legend
Static validators do not establish live model behaviorWalkthrough steps name evidence and verification limits
A repository-reading author cannot establish newcomer successGuide 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 missing pptxgenjs; rerunning just test-deck-render with the bundled Node dependency succeeds, including geometry checks and rasterizing 12 slides. The optional PowerPoint validator skips because the chosen Python lacks lxml/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"
    }
  ]
}