cast-lessons

Every session captures its own corrections at best. Nobody reads the corrections across the team, so the same one is made in ten threads.

Lessons belong to a project (docs/architecture/line-profile.md LP5). Run from the root of the repository whose lessons you are mining, and read its profile first with cast flow profile --json: its project is where the signals go, and its principles are the project's own files, which new principles are written into. The clusters are matched against those files and the shared set together; cast goals --json returns both as one text (principles). A repository without a profile is mined the same way against the shared set alone, and its signals carry no project.

Find the corrections

cast search "don't|do not|never|stop|wrong|not like that|instead|revert" -s <window> -n 50
cast search "why did you|I said|again" -s <window> -n 30

The first line's words are REDIRECT_WORDS in packages/shared/contracts/redirectWords.ts, the same words the session insight keeps when it samples a long session.

When mining one project, keep the search to its sessions (add repo:<name> to the query). For each hit, cast read <id> <line> with a few messages of context to see what the agent did and what the human wanted instead. Keep the ones where a human corrected an agent; drop agent to agent messages and corrections that were about a one time misunderstanding.

Cluster

Group by the rule that would have prevented them, not by the words used. Three sessions told to stop rewriting files they did not own are one rule. For each cluster: the rule in one sentence, how many sessions hit it, the short ids, and whether the repository's instructions already say it (read them; a rule that is written and still ignored is a different problem than one that is missing).

Then match each cluster against the shared set and the project's principles files. A cluster is that principle when the principle, as written, would have prevented every correction in it; one that only shares a topic is not. A match is a repeat of a rule the team already holds, and its count belongs to that principle. A cluster with no match, seen in two or more sessions, is a candidate principle: write it as the file writes them (the principle, why it matters, the evidence) under the next free id in its area, in that file's own id scheme, so a project's ids keep its prefix.

Propose

For each cluster, one of:

• A line for the project's agent instructions, written as a principle, with the exact place it belongs.
• A decision: cast decisions add, when the correction was really a choice the team has now made.
• Nothing, with the reason: the rule is present and the fix is elsewhere (a hook, a tool, a prompt), named.

File each cluster as a signal

A cluster that needs a change goes through the signal door, so the flow can take it up as a cause, and the same rule seen next week counts toward that cause instead of opening another:

cast signal add --source lesson --kind cohesion --project "<the profile's project>" \
  --fingerprint lesson:<rule-slug> \
  --title "<the rule, one line>" \
  --subject <the instruction file or area it concerns> \
  --detail - <<'BODY'
<how many sessions hit it, their short ids, and the proposed line or decision>
BODY

The fingerprint names the rule, not this week's wording, so a rerun over a later window lands on the same cause. A cluster that matches a principle uses the principle's id (lesson:PR-code-4), so every repeat counts toward that principle's cause, and the detail says what the principle failed to prevent this time: missing from the instruction the agent read, or present and ignored. A candidate principle uses its own slug and carries the proposed text in the detail. A signal only suggests a cause, so file it in both modes. File from the repository's root, so the profile's workspace applies along with its project.

Report as a table ordered by frequency, with the signal and the cause each cluster reached. With write, apply the instruction lines, record the decisions, add each candidate principle to the project's principles file and update the evidence line of each matched one, then say what went where. Without it, the table is the deliverable and the human chooses.