["design artifact with impact graph","acceptance criteria","file changes","leverage and negative leverage"]
requires
["substantial change or explicit design need"]
calls
[]
Design
Core Principle
Coherent design: every decision traces to a named incoherence, and every artifact affected by the decision is enumerated before implementation begins.
If you can't name the incoherence, you don't have a design problem. If you can't enumerate what your change affects, you don't have a design — you have a guess.
Algorithm
Define — name the incoherence, the parts, and the failure mode.
Unfold — walk the design through problem, constraints, impact graph, proposal, acceptance criteria, and file changes.
Rules — make each subsection mechanically actionable with explicit ❌/✅ examples.
1. Define
1.1. Identify the parts
Problem (the named incoherence)
Constraints (what can't change, what contracts govern)
Proposal (what to build, with types and interfaces)
Impact graph (what consumes, produces, or copies the changed thing)
Acceptance criteria (specific file + specific check + pass/fail)
❌ "We need better version handling" (unnamed incoherence)
✅ "Version is duplicated in 5 files with no single source of truth — #22" (named, numbered)
✅ "Actor FSM allows Idle→Processing but daemon never checks for re-entry — #12" (named, located)
1.2. Articulate how they fit
The problem names what's wrong; constraints bound what you can touch; the proposal changes the minimum to close the gap; the impact graph ensures nothing is missed; ACs verify the gap is closed
Design fails via incomplete impact tracing — changing the node without following the edges. The proposal fixes one artifact but breaks or neglects the artifacts that consume it.
❌ "Updated the skill, canonical doc will catch up later"
✅ "Skill declares canonical doc as authority → canonical doc must be updated in the same change, or authority claim must be explicitly narrowed"
2. Unfold
2.1. Problem
State the incoherence precisely before proposing anything.
2.1. Name the incoherence, not the feature
❌ "Add a VERSION file" (solution, not problem)
✅ "Version is duplicated across 5 files — bumping requires 5 manual edits, forgetting any breaks CI" (incoherence)
2.2. Distinguish schema from population
❌ "Lockfile doesn't support package versions" (wrong — schema has version/source/rev/subdir)
✅ "Lockfile schema has version field but first-party entries populate it with placeholder 1.0.0" (population problem)
2.3. Show evidence
❌ "This has caused problems"
✅ "v3.8.0 shipped with v3.7.4 version string. Three patch releases to fix. Pi reported v3.7.3 when binary was v3.8.2."
2.4. Enumerate all failure modes
❌ "cn update version comparison is broken" (one failure mode)
✅ "Three independent failures: CI doesn't upload assets (404), binary naming mismatch (x64 vs x86_64), version-only comparison (no same-version patches)" (all three)
2.2. Constraints
Identify what governs before proposing what changes.
3.1. Name existing contracts
What authority relationships exist? What documents govern on disagreement?
❌ "We'll update the skill"
✅ "Skill §Authority says canonical doc governs on disagreement — so canonical doc must be updated, or authority claim must be narrowed"
3.2. Name the abstraction level
❌ "Use language-specific build metadata as version source" (wrong level for system manifests, lockfiles, tests, status)
✅ "VERSION file is language-agnostic, sits above all consumers: build system, system manifest, package manifests, lockfiles, tests, CI"
3.3. Name what can't change
❌ Proposal silently breaks an existing interface
✅ "Lockfile format is consumed by cn deps restore — schema stays, population changes"
3.4. Name the architecture assumption you are challenging
State which existing boundary, ownership model, or system assumption is no longer serving the system.
❌ "We need a cleaner design"
✅ "This change challenges the assumption that every new capability family must be hardcoded in trusted core"
✅ "This change challenges the assumption that communication is just a capability rather than a body/medium subsystem"
2.3. Impact Graph
This section is not optional. Trace everything the change touches.
4.1. Enumerate downstream consumers
What reads, renders, or acts on the artifact you're changing?
❌ Update CDD skill, forget post-release template consumes the new metrics
✅ "cnos.cds/skills/cds/CDS.md §"Assessment" → §"PRA contents" defines metrics → post-release template must render them → review skill must tag findings by type"
✅ "Adding a new FSM state → check: protocol interface, doctor checks, status output, packed context renderer, tests"
4.2. Enumerate upstream producers
What produces the inputs your design depends on?
❌ "Tests will use the version" (which version? from where?)
✅ "VERSION file → build generates version module → core library reads it → tests derive from the exported version constant"
4.3. Enumerate copies and embeddings
Where does the same information appear in multiple places?
❌ "Update src, packages will sync"
✅ "src/packages/cnos.cdd/skills/cdd/CDD.md is the canonical source; docs/gamma/cdd/CDD.md is a human-facing pointer and must continue to point to the right canonical path"
4.4. Name authority relationships
If two artifacts carry the same information, which governs?
❌ Both skill and canonical doc have the rule, unclear which wins
✅ "cnos.cds/skills/cds/CDS.md is the normative source for the software-cycle lifecycle algorithm (CDD.md owns the generic CCNF kernel). Role skills (alpha/, beta/, gamma/) expand execution detail for their role. Each fact lives in exactly one place — skills do not restate canonical rules, they add role-local detail that CDS.md does not cover."
4.5. Trace rule changes through all embeddings
When you add a rule, find every artifact that embeds, templates, or implements that rule
❌ Add review quality metrics to CDS, forget post-release template still has old 4-section output
If the proposal adds artifacts, gates, or process, state:
who must produce them
who consumes them
why a lighter alternative is insufficient
❌ "Require another artifact for rigor"
✅ "Require SELF-COHERENCE.md for governance branches because reviewer and releaser need branch-local proof that the branch followed the process it defines"
5.8. State the automation boundary
Say what should remain human judgment and what should become script/CI/lint.
❌ "Reviewers will keep checking stale paths manually"
✅ "Artifact presence, placeholder rendering, and stale path refs should be automated; α/β/γ judgment remains human"
5.9. Simplest thing that closes all failure modes
KISS/YAGNI, but don't confuse "simple" with "incomplete"
❌ "Fix version comparison" (1 of 3 failure modes — CI upload and naming still broken)
✅ "Three failures, three fixes: CI uploads assets, naming made consistent, comparison includes commit hash"
5.10. Name what you're not doing
❌ Non-goals absent
✅ "V1 does not: score α/β/γ semantically, decide MCA vs MCI correctness, replace review dialogue"
2.5. Acceptance Criteria
ACs are the contract between design and implementation.
6.1. Map each AC to a specific file and check
❌ "The system handles version coherence correctly" (unfalsifiable)
✅ "grep -rn for version string returns exactly one source file (VERSION)" (file + check + pass/fail)
6.2. No charitable interpretation
Each AC must be mechanically verifiable — not "I believe this is met because..." but "file X, line Y, present: yes/no"
❌ "AC4 is met because §11.11 covers review metrics" (belief, not evidence)
