Menu
Immutability contract for all pipeline stages: artefact freeze, V-AC parity, non-code parity, anti-tautological rule, and return-to-source transition.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Schema and migration semantics for /dr-doctor — thin one-liner contract, 6-pass migration, data-loss safety, conflict resolution. Loaded by self-heal.
Core Datarim rules. Load this entry first, then only the fragment needed for paths, storage, numbering, backlog, routing, or archive behavior.
Post-QA hardening — detects task type (code, docs, research, legal, content, infra) and applies the matching verification checklist before archiving.
Testing pyramid, frameworks, mocking. Load first; then the fragment for the active gate (live smoke, silent failure, bats, legacy triage).
Preserve Datarim task continuity while orchestrated Claude Code or Codex sessions compact or clear context at deterministic pressure thresholds.
Init-task artefact: verbatim operator brief + append-log, mandatory read by every pipeline command. Source of truth for operator intent.
Based on SOC occupation classification
| name | immutability |
| description | Immutability contract for all pipeline stages: artefact freeze, V-AC parity, non-code parity, anti-tautological rule, and return-to-source transition. |
Authority: RFC 2119 keywords (MUST / MUST NOT / SHOULD / MAY) apply throughout. Foundation: Design by Contract (Meyer, 1986) — preconditions and postconditions are non-negotiable specifications. ADRs (Nygard, 2011) — accepted decisions are immutable; changes are made by superseding, not editing. Configuration Management (IEEE 828-2012) — a baseline changes only through formal change control procedures.
This skill defines the immutability contract for every Datarim pipeline stage. An artefact produced by a stage MUST NOT be weakened to accommodate a constraint discovered in a downstream stage. When a genuine constraint makes an artefact unsatisfiable, the Return-to-Source Transition provides the formal revision path.
Loaded by every pipeline command (dr-prd, dr-plan, dr-design, dr-do,
dr-qa, dr-compliance) and by the architect and developer agents.
Frontend-UI tasks additionally load the ## Frontend-UI Rules fragment.
Each command reads the section matching its stage. The general section and common rules are always loaded; per-stage fragments are loaded conditionally by the consuming command.
An artefact produced by a pipeline stage MUST NOT be weakened to accommodate a constraint discovered in a downstream stage.
An artefact is "weakened" when:
Valid responses to a constraint that makes an artefact unsatisfiable:
V-AC rows at every stage are subject to the same immutability. A V-AC that
verifies a deliverable MUST NOT be changed to a weaker check so the
deliverable passes without meeting the original criterion. This rule extends
the TDD discipline's V-AC parity rule (skills/testing/tdd-discipline.md:143)
to all pipeline stages.
For non-code tasks, the to-do / checklist is the "test." A checklist item
MUST NOT have its completion criterion weakened. "Checklist scope reduction"
is the non-code equivalent of weakening a V-AC assertion. This rule extends
skills/testing/tdd-discipline.md:149 to all stages.
A verification criterion MUST be falsifiable. A criterion that always passes
regardless of the state of the implementation is a tautology and MUST be
removed or re-scoped. Examples: "check that the file exists" (always passes
if the implementation creates it), "check that variable X is truthy" (always
passes if the test runner initialises it). This rule generalises
skills/testing/tdd-discipline.md:101-116 to all verification criteria
across all stages.
When an artefact genuinely cannot be satisfied as written, the stage executor MUST NOT silently change it. Instead, follow this transition:
Trigger: A real blocker that genuinely requires changing an immutable artefact (test, V-AC, checklist item, design decision, QA criterion, compliance criterion, visual baseline) — not implementation difficulty (which is never a valid reason), but a discovered constraint (impossible preconditions, wrong level of specification, newly understood requirement, upstream API change that invalidates the original contract).
Who decides: The stage executor cannot decide alone. Escalate to the operator with: (a) the original artefact text verbatim, (b) the concrete reason it must change, (c) the proposed new text.
Where it is recorded:
In datarim/tasks/{TASK-ID}-task-description.md § Decisions, with the format:
Return-to-source: <artefact-id> (stage: <stage-name>)
original: <verbatim original text>
reason: <rationale for the change>
proposed: <verbatim proposed new text>
routes-to: /dr-<target-stage> {TASK-ID}
The record is written BEFORE the artefact is changed.
How the stage resumes: After the operator approves the revision and the upstream stage updates its artefact (or re-issues it), the stage executor resumes work. The CTA after recording the transition MUST route to the target stage (the stage that owns the immutable artefact), not continue the current stage.
Routing table:
| Artefact being changed | Owned by | Routes to |
|---|---|---|
| PRD V-AC / D-REQ | /dr-prd | /dr-prd {TASK-ID} |
| Plan V-AC / Implementation Step | /dr-plan | /dr-plan {TASK-ID} |
| Design decision (creative doc) | /dr-design | /dr-design {TASK-ID} |
| Test / V-AC verification command | /dr-do (recorded in plan) | /dr-plan {TASK-ID} |
| QA criterion / Layer structure | /dr-qa | /dr-qa {TASK-ID} |
| Compliance checklist item | /dr-compliance | /dr-qa {TASK-ID} (re-verify) |
| Visual baseline (frontend) | /dr-do (with operator sign-off) | /dr-do {TASK-ID} |
What this is NOT:
Each fragment is loaded conditionally by the command that owns the stage. The fragment defines the stage's immutable artefact, supersede path, and stage-specific immutability rules.
Immutable artefact: PRD V-AC rows and D-REQ requirements in
datarim/prd/PRD-*.md.
Supersede path: New PRD file with supersedes: frontmatter; old PRD
marked superseded.
Return-to-Source trigger: Requirement contradiction discovered in any
later stage. Route to /dr-prd {TASK-ID}.
Stage-specific rule: PRD V-AC rows are MUST-level. They define the specification that all downstream stages satisfy. Changing a PRD V-AC to accommodate an implementation constraint is forbidden. If the PRD V-AC specifies the wrong contract, the operator authorises a PRD revision via the Return-to-Source Transition.
Mapped from /dr-qa FAIL-Routing: When QA fails at Layer 1 (PRD
Alignment), the CTA routes to /dr-prd {TASK-ID} — consistent with this
fragment's routing.
Immutable artefact: Plan V-AC rows and Implementation Steps in
datarim/plans/{TASK-ID}-plan.md (L3-L4) or
datarim/tasks/{TASK-ID}-task-description.md (L1-L2).
Supersede path: New plan revision (-v2) overwrites; original plan
archived in documentation/archive/.
Return-to-Source trigger: V-AC or Implementation Step change needed
during /dr-do. Route to /dr-plan {TASK-ID}.
Stage-specific rule: Plan V-AC rows are SHOULD-level at plan time,
becoming MUST-level once /dr-do begins. A plan V-AC can be refined
(verification method changed) without reaching back to PRD, provided the
underlying requirement does not change. Contradiction between plan and PRD:
the PRD is the higher authority — the plan is wrong.
Mapped from /dr-qa FAIL-Routing: When QA fails at Layer 3 (Plan
Completeness), the CTA routes to /dr-plan {TASK-ID}.
Immutable artefact: ADR-calibre decisions in
datarim/creative/creative-*.md (sections that carry Options + Pros/Cons
Supersede path: New creative file with supersedes: frontmatter pointing
to the superseded file. L2 tasks MAY use a lightweight § Design Amendment
appendix with operator sign-off instead of a full new creative doc.
Prose amendments stay prose — decided 2026-08-02. A machine-readable immutable-sidecar mechanism (validator, creator, template, chain ledger, three suites) was proposed and is NOT adopted. Measured demand at decision time: 274 PRDs in the workspace and zero
§ Design Amendmentsections in any of them — the lightweight path above has never once been exercised. Building enforcement infrastructure for a workflow with no observed usage adds surface to maintain and a gate to keep green, in exchange for nothing. Revisit if prose amendments start appearing and drift becomes a real problem; the trigger is usage, not tidiness.
Return-to-Source trigger: Design deviation discovered during /dr-do or
/dr-qa. Route to /dr-design {TASK-ID}.
Stage-specific rule: Not every detail in a creative doc is frozen.
Supporting material (research notes, exploration dead-ends, implementation
notes) is mutable. Only decisions that carry architectural weight (Options
evaluated, explicit Decision, impact across >=2 components) are immutable.
If a /dr-do implementation hits an implementation detail the design
explicitly deferred, no Return-to-Source is needed.
Mapped from /dr-qa FAIL-Routing: When QA fails at Layer 2 (Design
Conformance), the CTA routes to /dr-design {TASK-ID}.
Immutable artefact: Tests (code tests, checklist items, V-AC verification
commands). For code tasks, the Test Immutability Rule from
skills/testing/tdd-discipline.md:117 is the canonical text. This fragment
provides the routing table entry and the generalised V-AC/Non-Code parity
rules.
Return-to-Source trigger: Failing test or V-AC cannot be satisfied as
written. Route to /dr-plan {TASK-ID} (or /dr-prd {TASK-ID} if the
requirement itself is wrong).
Stage-specific rule: The Test Immutability Rule ("a test MUST NOT be
weakened") is the canonical /dr-do discipline. The V-AC Parity Rule and
Non-Code Parity Rule from the common rules apply with equal force. The
Return-to-Plan Transition from skills/testing/tdd-discipline.md:153 is
the implementation of the Return-to-Source Transition for this stage.
Relationship to tdd-discipline.md: This fragment does NOT duplicate
the Test Immutability Rule or the Return-to-Plan Transition. It references
tdd-discipline.md as the canonical source for those. The common rules
section of this file provides the generalised template; tdd-discipline.md
provides the concrete /dr-do discipline.
Mapped from /dr-qa FAIL-Routing: When QA fails at Layer 4 (Code
Quality), the CTA routes to /dr-do {TASK-ID}.
Immutable artefact: QA Layer structure (what is checked — the Layer templates, the DoD checklist items). The committed QA report after a verdict is issued is append-only.
Supersede path: New QA report with -v2 suffix; original report kept for
audit trail.
Return-to-Source trigger: QA criterion needs change that would weaken
a verification gate. Route to /dr-qa {TASK-ID} (re-run after operator
approval). If the change originates from a compliance finding, route to
/dr-qa {TASK-ID}.
Stage-specific rule: The structure of what is checked is immutable; the specific invocation (which linter, which threshold, which test runner command) is mutable. Tool versions, linter thresholds, and test runner commands evolve as the framework improves — freezing the exact command would prevent beneficial upgrades. Only the structure of what is checked is frozen.
FAIL-Routing consistency: The immutability skill's routing table MUST
match /dr-qa's existing Layer-to-command FAIL-Routing map from
skills/cta-format/SKILL.md § FAIL-Routing. The two tables describe the
same routing from different perspectives: the CTA format defines the
CTASE block shape; this skill defines the contractual basis for the routing.
Immutable artefact: The 7-step compliance checklist structure. The committed compliance report after a verdict is issued is append-only.
Supersede path: New compliance report with -v2 suffix.
Return-to-Source trigger: Compliance criterion needs change that would
weaken a compliance gate. Route to /dr-qa {TASK-ID} (re-verify after the
QA criterion is revised).
Stage-specific rule: The 7-step checklist structure (which checks are run, in what order) is immutable; the tool version and threshold per step (which linter, which coverage floor) is mutable. The Anti-Tautological Rule applies to every checklist item: a criterion that always passes is a tautology and MUST be removed or re-scoped.
Immutable artefact: Approved visual baseline (explicit screenshots for L3-L4 tasks; implicit "current production look" for L1-L2 tasks). Design token values (colour, spacing, typography) as recorded at design approval time.
Supersede path: New baseline capture replaces old at operator approval;
old baseline archived in datarim/qa/playwright-{ID}/.
Return-to-Source trigger: Visual deviation that is not operator-approved.
Route to /dr-do {TASK-ID}.
Stage-specific rule: The approved visual baseline MUST NOT be silently weakened. If a change introduces a visual difference, it MUST be explicitly approved (the operator reviews the diff and confirms), not silently accepted as "close enough." This mirrors the Chromatic approval workflow and the Anti-Tautological Rule's principle that "passing is not sufficient — the test must be able to fail."
L1-L2 tiering: For L1-L2 frontend tasks, the baseline is implicit ("current production look"). The change either looks the same (PASS) or different (requires operator inspection). Explicit screenshot baselines are required only for L3-L4.
Enforcement: Tier 1 (in-context directive) is the primary mechanism.
Tier 2 (operator diff review via Playwright evidence at /dr-qa Layer 4f)
is the safety net. A deterministic pixel-diff gate (Tier 3) is a deferred
future evolution.
dr-prd.md, dr-plan.md, dr-design.md, dr-do.md,
dr-qa.md, dr-compliance.md — load the immutability skill and their
stage-specific fragment.architect.md, developer.md — load the immutability skill
(already loaded via the command that spawns them).frontend-ui/SKILL.md — loads the Frontend-UI Rules fragment./dr-qa Layer 3 adds an immutability sub-check (future
enhancement — deferred to TUNE-NNNN).dev-tools/check-v-ac-integrity.sh (future —
deferred to TUNE-NNNN).