record

Files (5)

• SKILL.md
• process_feedback.ncl
• process_feedback_apply.ncl
• tech_debt.ncl
• tech_debt_apply.ncl

SKILL.md (first lines)

# 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.** One writer per node-kind-and-namespace, whoever it
is (the pen law — [`docs/entries.md`](../../docs/entries.md)): **testimony**
is signed by the walker who witnessed it and committed by that walker,
append-only, into `.ledger/deposits/<topic>/<signer>/`; **synthesis,
decision, and narrative** nodes — and every promotion — are the composer's.
In a **solo** predicate walk there is no composer: the walker signs
everything and executes this skill directly. Two writers interleaving one
namespace 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)](#recording-continuous) and
[Promotion](#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:
```bash
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:
```bash
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](../../ambient.md#planning-invariants)) keeps the graph
linear and reconstructable.

---

## Promotion

### Destination routing (the combinator's dispatch table)

From nrdxp/predicate, MIT.

More from nrdxp/predicate