| name | record |
| description | Durable categorized record-keeping for any predicate-enabled walk.
Trigger when:
- Classifying a step's output for recording (decision, finding, debt, feedback).
- Promoting a scratch artifact to the ledger, to repo/docs, or to a category
home (.ledger/tech-debt/, .ledger/process-feedback/).
- Auditing whether a draft is structurally ready for its destination.
- Running a zero-context sensibility read before committing to promotion.
- Recording a known limitation as a tech-debt entry (not prose in the log).
- Recording a friction, miss, improvement, or process amendment.
- Prompt contains: /record, record-keeping, promote, ledger note, zettelkasten,
scratch-to-ledger, zero-context read, over-strip, classification trigger,
tech-debt, process-feedback, amendment.
|
Record — Durable Categorized Records
Ambient — applies to every predicate-enabled walk, not campaign-only.
The RECORD primitive manages durable artifacts across three complementary
substrates. What distinguishes it from generic note-taking is the
category model: each category of durable artifact has a defined
contract (machine-checkable shape), a .ledger home, and a trigger
(when to record into it).
Category model
Who holds the pen. In an ensemble (campaign/council), the composer
alone writes the recorder — workers and seats deposit to scratch and the
composer classifies, promotes, and records. In a solo predicate walk
there is no composer: the walker holds the pen and executes this skill
directly. One pen per walk, whoever it is — two writers interleaving one
recorder is how a zettelkasten becomes a shoebox.
Each category = {contract, .ledger home, trigger}. Categories are
extensible: adding a fourth later is cheap — add the contract, home,
and trigger row.
| category | contract | .ledger home | trigger |
|---|
| flight-log | narrative; no formal contract | .ledger/log/ | at every significant step: decision, pivot, finding |
| tech-debt | skills/record/tech_debt.ncl | .ledger/tech-debt/ | when a limitation is accepted rather than fixed |
| process-feedback | skills/record/process_feedback.ncl | .ledger/process-feedback/ | when friction, a miss, an improvement, or a live process amendment is identified |
The flight-log category (existing)
Narrative zettelkasten — linked, curated trail of how the space was
explored: decisions, pivots, adjustments. NOT exhaustive; navigable
graph. See Recording (continuous) and
Promotion for the full flight-log model.
The tech-debt category (new)
A first-class, machine-shaped entry for a known limitation or deferred
decision — absorbs the campaign's "accepted limitations / tail" so they
are trackable and actionable rather than buried in prose log entries.
Fields: id (unique), claim (falsifiable statement), location
(file:line, gate, or component), severity (critical|high|medium|low),
why_deferred, signpost (what would resolve or invalidate it).
Instance format: YAML, validated via:
nickel export <file>.yaml --apply-contract skills/record/tech_debt_apply.ncl
Trigger: when you accept a limitation rather than fix it — record
it here, not in prose. A signpost is required so the debt is not just
named but actionable.
The process-feedback category (new)
Captures friction, missed signals, improvements, and AMENDMENTS. An
AMENDMENT is the highest-stakes kind: the agent changed a live process
rule and it was a good idea. This makes process changes durable rather
than living only in conversation recall.
Fields: id (unique), kind
(friction|miss|improvement|amendment), context (situation that
triggered it), outcome (what changed or what it means).
Instance format: YAML, validated via:
nickel export <file>.yaml --apply-contract skills/record/process_feedback_apply.ncl
Trigger: when friction surfaces, a signal is missed, the process
improved, or a live rule was amended. AMENDMENT kind requires that the
rule change was nrd-approved or demonstrably beneficial — it is a record
of accepted change, not a unilateral rewrite.
Three substrates with distinct roles
| substrate | role | character |
|---|
scratch | exhaustive working detail; coherent context being built | default ephemeral; sometimes a draft staged for promotion |
ledger (.ledger/) | all category homes: flight-log, tech-debt, process-feedback | curated, linked, durable; each category in its own home dir |
repo/docs/ | promoted durable artifacts (a design that graduated) | permanent |
Promotion is the combinator promote(from, to) over {scratch, ledger, repo}.
The destination is routed by purpose, not by artifact type.
Recording (continuous)
At each significant step, classify the output and record it — this is a
classification trigger, not a rulebook. Ask: what kind of thing just happened?
| what happened | where it goes | minimum record |
|---|
| decision / pivot / adjustment | linked ledger note (flight-log) | what, why, which [[decisions/KUs]] it changes; link to superseded/resolved notes |
| finding (new R/I/U item) | update the live R/I/U tracker; ledger note if it pivots direction | tracker entry with grounding + last_validated + signpost |
| accepted limitation | .ledger/tech-debt/<id>.yaml | tech-debt record validated against tech_debt.ncl |
| process friction / miss / improvement / amendment | .ledger/process-feedback/<id>.yaml | process-feedback record validated against process_feedback.ncl |
| working detail / draft | scratch | no ceremony; stage for promotion when ready |
Linking discipline (flight-log). Ledger notes are a zettelkasten: each note
links (supersedes, resolves, blocks, see-also) to the nodes it affects.
The ledger is a navigable graph, not a flat append log. Every-touch-commit
(Sketch Commit Discipline) keeps the graph
linear and reconstructable.
Promotion
Destination routing (the combinator's dispatch table)
promote(from, to) routes by the artifact's purpose:
- needed to reconstruct how/why but not general documentation →
ledger (zettelkasten; future agents in this exploration)
- a durable artifact useful to someone who never saw the exploration →
repo/docs (a user / zero-context agent)
- cross-cases:
scratch → ledger, scratch → repo, ledger → repo
The "stranger" for the zero-context sensibility read is parameterized by the
destination's audience. The over-strip line moves with the destination:
- ledger stranger — a future agent reconstructing this campaign; still
needs decisions + why
- repo stranger — a user who never saw the exploration; needs none of the
session context
Gate 1 — structural readiness (machine-checkable)
The artifact must conform to its destination's contract before promotion:
- a tech-debt record must pass
nickel export ... --apply-contract tech_debt_apply.ncl
- a process-feedback record must pass
nickel export ... --apply-contract process_feedback_apply.ncl
- a draft IBC must pass
worker_ibc.ncl export
- a DAG node must export cleanly against
dag.ncl
- a skill draft must carry valid YAML frontmatter (this file's own gate)
- a doc must have valid local links and header structure
Does not export / does not conform → not ready. Do not proceed to Gate 2.
This makes "structurally ready" machine-checkable rather than a judgment call.
Gate 2 — sensibility (zero-context multi-round read)
A quality mechanism, not a box to tick. Read the draft as a stranger with
only its stated purpose; surface everything that is only meaningful in-session:
- references to "what we discussed" or "as above"
- implicit assumptions the reader cannot recover
- scratch-isms (abbreviations, shorthand, agent-internal labels)
Strip or make-explicit each; iterate until a context-free read is fully sensible.
Over-strip guard — strip only what is session-meaningful AND not needed for
the stated purpose. Before stripping anything, ask:
Does a stranger with the stated purpose need this to understand / use the
artifact?
Yes → keep and make explicit. "Merely discussed in session" → strip.
Never strip load-bearing rationale. A sensibility read that removes
rationale is a context-destroyer, not a quality pass.
Depth scales with stakes and destination:
- routine scratch note → ledger: self-administered flush-read
- architectural or doctrine artifact → repo: decorrelated agent review
(refine REVIEW semantics)
Gate 3 — role authorization (privileged)
Promotion is role-gated:
| artifact class | who may promote |
|---|
| working detail / findings → ledger | any walker |
| full architecture / spec → repo/docs | architect-tier |
| doctrine edits (rules.md, ambient.md, formalism) | Reserved halt — human approval required before merge |
A worker cannot unilaterally promote to durable doctrine. On doctrine promotion,
emit the draft and halt for human review before touching the destination.
On promote: link the durable artifact
After promotion:
- Strip ephemera (Gate 2 already handled this).
- Write a ledger note recording the promotion: what was promoted, where it
landed, and why it graduated. This keeps the zettelkasten honest about the
artifact's provenance.
Project-local validation
A project (predicate-self-hosting + downstream) records its own tech-debt and
process-feedback through the project-local gate mechanism. Register a gate
script in .ledger/gates/ that validates the records:
#!/usr/bin/env bash
set -euo pipefail
root="${1:-}"
skill_dir="$root/skills/record"
for f in "$root/.ledger/tech-debt"/*.yaml 2>/dev/null; do
[[ -f "$f" ]] || continue
nickel export "$f" --apply-contract "$skill_dir/tech_debt_apply.ncl" >/dev/null \
|| { echo "tech-debt record failed: $f" >&2; exit 1; }
done
for f in "$root/.ledger/process-feedback"/*.yaml 2>/dev/null; do
[[ -f "$f" ]] || continue
nickel export "$f" --apply-contract "$skill_dir/process_feedback_apply.ncl" >/dev/null \
|| { echo "process-feedback record failed: $f" >&2; exit 1; }
done
The project-gates.sh runner discovers and executes this script automatically
on each commit when a walk is registered. Projects with no .ledger/gates/
directory incur zero overhead (the runner is a clean no-op).
Adaptive extension
This skeleton fleshes against the concrete R/I/U at hand. Minimum floor:
- Recording: classify the step; write the minimum record for its class.
- Promotion: pass structural readiness (Gate 1) before touching Gate 2.
Extend selectively when not converged: add rounds to the sensibility read when
the artifact is high-stakes or the over-strip risk is real; add a decorrelated
reviewer when promoting doctrine; tighten the linking discipline when the ledger
is the primary reconstruction surface.
The skeleton supports shape AND flexibility — it does not prevent movement. Do
not inflate it into an exhaustive script.
Two-purpose inheritance
Following P-GROUND's two-purpose principle:
- Recording — formal gate: did you classify and record the step? (presence-
checkable); substantive gate: is the trail reconstructable? (closed by review).
- Promotion — formal gate: does the artifact pass structural readiness?
(machine-checkable via contract conformance); substantive gate: is the
zero-context read fully sensible? (closed by the multi-round read + role-gated
reviewer, depth-to-stakes).
The contract is the "did-they-try" floor that feeds the review; the review is
where substance is judged. Do not fake a smarter contract.
