Project Principles

Source identity (from 01-frame/principles.md):

ddx:
  id: helix.principles
  depends_on:
    - helix.prd
    - helix.product-vision

Project Principles

These principles guide judgment calls across all HELIX activities when working on HELIX itself. They are not workflow rules or process enforcement — they are lenses applied when choosing between two valid options. The only constraint: principles cannot negate HELIX mechanics (artifact authority order, activity gates, tracker semantics).

This file was authored from the vision; mechanics-describing items below (authority is the resolver; documents are the contract; alignment is continuous; work flows in every direction) read as principles but are actually load-bearing HELIX mechanics. Treat them as principles only in the sense that they steer judgment about how to extend HELIX itself.

Principles

Authority is the resolver. Conflicts between artifacts resolve up the authority order, never down. Source code never overrides specification.
Documents are the contract. Every consequential decision lands as an artifact update. If a decision is not in the documents, it does not exist.
Alignment is continuous. The loop runs always; drift is caught early, not in a quarterly audit. The alignment skill is the operator of this rule.
HELIX doesn’t run anything. Execution is the runtime’s job — DDx, Databricks Genie, Claude Code, anything that reads and writes files. HELIX produces aligned documents and plans; the runtime executes them.
Less is more. HELIX owns the methodology and one skill — not the toolbox. Every feature added to HELIX is weighed against “could this live in the runtime instead?”
Work flows in every direction. A test exposes a design gap; a metric revises a feature spec; a vision update propagates down. The activity names locate the kind of work, not its position in a sequence.
Discipline over improvisation. AI agents improvise well; the value of HELIX is the discipline that makes improvisation reviewable.

Tension Resolution

When these pull against each other	Resolve by
Less is more vs. methodology depth	Trim. If a methodology detail can live in `workflows/` or a glossary page rather than a flagship artifact, move it there.
HELIX doesn’t run anything vs. operator convenience	Move the convenience to the runtime adapter, not HELIX. Wrappers that shorten DDx invocations are DDx’s job.
Documents are the contract vs. ship-it pressure	Capture the decision as a document update before merging; otherwise the change exists only in code and the artifact graph diverges.

Size Guidance

Keep this file under ~60 lines. If a principle requires more than two sentences to explain, it is probably a methodology document, not a principle. Move the long-form rationale to workflows/README.md or a dedicated explainer and leave one-line guidance here.