Skip to content

Knowledge loop

How the record of a finished task is distilled into the knowledge base on Friday, and how the next plan cites it.

The workflow guide ends at a draft PR. This guide covers what comes after: where the record of a finished task goes, and how it comes back to the next task.

How it works

One turn of the loop

A finished task becomes knowledge on Friday, and the next plan cites itA task starts as a request and passes the plan file, the slice loop and a draft PR, and what actually happened is left in the plan’s Outcome. A Friday lane distills that record into decision notes and concept notes in the knowledge base, and on Monday last week’s signals become proposed changes to rules and gates. Before the next plan is written, it looks up past decisions in the knowledge base and cites them.Requestthe size is setPlan filecites past decisionsSlice loopbuild, review, commitDraft PRa person mergesOutcomewhat happenedFriday distillinto decision notesKnowledge baseconcepts, overviewMonday feedbackproposed changes

The left column is the path of one task, and the right column is the path that turns once a week. No one tidies the record by hand. The plan file fills up while the work runs, and lanes read that file at set times.

The plan file is the raw material

The plan holds the intent, and the Outcome holds what actually happenedThe main sections of a plan file are Spec, Acceptance Contract, Boundaries, Seams, Slice Queue, Verification Commands, Decisions and Outcome. The plan step writes the first seven. Within them, the implementer fills in the contract’s verdict cells, and a slice is ticked when it passes the review gate. The Outcome is where implement, review, fix and ship record the review verdicts, the fix-loop counts and the commits as they happened.Specwhat done meansAcceptance Contractverdicts by implementBoundariesdo and don’tSeamspublic boundariesSlice Queueticked on review passVerificationcommands that measureDecisionschoices and whyOutcomeverdicts, counts, commitsIntentthe plan writesFactsthe run fills in

The plan says what the work means to do, and the Outcome says what actually happened. How often a slice failed review, how often it was fixed, and which commits went in all stay in the Outcome. Monday's compound reads a fix loop that ran twice or more as a sign of a mistake that could have been avoided.

Besides plans, distillation also collects bug investigation reports and the notes left at the end of a session.

Lanes run on Friday

Friday lanes tidy up the week’s record, and Monday’s compound reads the signalsOn Friday at 11:45 the repos are synced, and from 12:00 to 13:00 caches and tools are cleaned and the code graph is indexed again. At 14:00 repo health metrics are collected, and at 15:00 the weekly retro writes down friction. Plan distillation runs at 16:00 and session memory distillation at 16:30. At 17:00 friction is collected on even weeks, and at 18:00 a cleanup runs on odd weeks. At 19:30 the search index is tidied. On Monday at 11:00, compound reads the signals of the retro, plan distill, friction and cleanup lanes and proposes changes to rules and gates, which a person approves.11:45Syncrepos up to date12:00Environmentcaches, tools, code graph14:00Repo healthmetrics, regressions15:00Weekly retrofriction written down16:00Plan distilldecisions, concepts16:30Memory distillsession memory notes17:00Frictioneven weeks18:00Cleanupodd weeks19:30Search indexleftovers removedMon 11:00compoundproposes, a person approves

macOS launchd runs the lanes at set times, so I don't have to remember them.

  • Distillation — the plan distill turns records into decision notes, and when three or more similar notes gather, it writes what they share as a concept note. At the end of the lane it rewrites a one-page overview of the knowledge base.
  • Proposals — compound and friction reports are only proposals, so they are written outside what search can see. Only a report that passes both a mechanical check and a small model's review moves into search. This keeps an unchecked proposal from being found as if it were knowledge. Whether a rule change compound proposes is actually applied is my call.
  • Team wiki — the retro lane picks documents worth promoting to the team wiki, and I decide whether to promote them.

The next plan cites it

Before a plan is written, past decisions on the same topic are looked up in the knowledge base. A decision that turns up is cited rather than made again, and an alternative rejected before is not proposed again. A past decision is treated as a hypothesis: the first line of the implementation checklist checks that its premise still holds.

My config

One distilled decision note

This note was distilled on a Friday from the plan for showing progress while aicommit2 generates commit messages. It carries the source plan path and the commit, so the note leads back to the raw material. The "rejected" rows in the table are the alternatives the next plan will not propose again. I cut the implementation decisions down to one. The note is written in Korean; this is a translation.

docs/aicommit2-progress-settled-requests.md
---
kind: doc
type: decision
status: adopted
domain: [aicommit2]
links: ["[[plan-aicommit2]]"]
---

# Progress unit = settled Request — message axis and token axis rejected

Response to Issue #258 ("loading slider while generating commits"). The root cause is not
missing feedback but **false feedback**: the empty-state text `⚠ No commit messages were
generated` renders before any response arrives, declaring failure while work is still running.

## Decision

| Option | Decision | Reason |
|---|---|---|
| Progress unit | **settled Request** = (provider, model) pair | Denominator Σ models is fixed before start. Success and failure both count → denominator always reached |
| Message unit | Rejected | With `generate` (1-5/model), one failure leaves the denominator unreached — a counter stuck at `4/6` reproduces #258 inside the fix |
| Token-axis %/slider | Rejected | No denominator exists (ADR-0001) |
| Dead-air gap fix | Rejected | Measured ~50ms — imperceptible. The draft's MUST item died by measurement |
| Counter text | Unit noun dropped, `(2/3)` | Both `generated` and `responded` become a lie the moment a failure is counted |

## Implementation decisions

- **finalize at model level**: wrapping at provider level fires once for a `model: [a, b]`
  provider → stalls at `1/2`. With single-model providers the two levels match, so the defect
  stays hidden (why check V5 exists).

## Outcome

`99c0dcf` (feat: show settled-request progress while generating commit messages).

## Provenance

- `.claude/20260709/PLAN-11-06-20.md` (2026-07-09, #258)
- Related: aicommit2 repo `docs/adr/0001-progress-over-settled-requests.md`

## Timeline

- 2026-07-12 | Weekly distill.
- 2026-10-24 | Grouped into concept page [[aicommit2-implementation-lessons-2]] (concept-bulk).

The last Timeline line records that three or more aicommit2 decision notes were grouped into a concept note.

Skills and habits

Which step of the workflow each skill I reach for sits beside, what it does differently, and the habits that set in while using this harness.

Herdr

herdr, where every agent session runs — a sidebar that marks only agents waiting on me, /team worker panes, a branch token, and account switching.