Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
---
title: "The Stop hook reads what the person typed through the shared transcript filter, and counts its asks in note_asked"
author: Anirudhkumar-nanonets
date: 2026-10-29
branch: claude/fix-save-learning-prompts-84888d
cost: { minutes: 1, tokens: 7385 }
id: l-523d6adc
scope: repo
status: active
src: agent
touches:
- src/claude/note-signals.ts
- src/trace/claude.ts
- src/claude/skills-wiring.ts
- test/trail-words.test.ts
- src/skills/risk.ts
- src/claude/stop.ts
- src/cloud/diff.ts
- src/telemetry/contract.ts
---

## Decided
- The save ask's `typed()` (src/claude/note-signals.ts) calls `typedText` from src/trace/claude.ts, the filter every other learning path uses. Its own copy dropped any message starting with `<`, and Claude Desktop puts a `<system-reminder>` status block before every message the person types, so in Desktop sessions no correction or option pick was ever seen.
- `ownText` (src/trace/claude.ts) opens an artifact comment ("[Artifact comment sent to Claude]" … `=== BEGIN ARTIFACT COMMENT <token> ===`) to its quoted lines; before, the whole harness wrapper counted as typed.
- New event `note_asked` {kind, saved: repo|personal|no}, sent from `askForNote` on the stop after an ask (`stop_hook_active`). `askAnswer` checks the last "Stop hook feedback" line is trail's ask (it contains the ask's closing text), so another hook's block isn't counted.

## Tried and ruled out
- A property on `hook_ms` for the Stop hook: it is sent only when learned skills are enabled (src/claude/skills-wiring.ts), so most stops would go uncounted.
- A property on `note_saved` alone: it gives the saves but not how many corrections were asked about, so no share.

## Watch out
- Agent-facing text (session start, skill, asks) must not say "memory", "notes" or "rules": test/trail-words.test.ts bans them. Say "your own copy".
- `shellEdit` treats a write it can't name as a repo edit. A leading `cd` outside the repo, or full paths that all point outside it, now mean no edit; a bare `python3 - <<EOF … open(p,'w')` from the repo still counts.
- Writing a learning through a heredoc that mentions the skills switch words trips the pre-bash guard (src/skills/risk.ts); pipe the body from a file.

In the code: src/claude/note-signals.ts (`typed`, `CORRECTION_RULE`, `shellEdit`, `askAnswer`, `PERSONAL`), src/trace/claude.ts (`ownText`), src/claude/stop.ts (`askForNote`), src/cloud/diff.ts (`branchAddsLearning`), src/telemetry/contract.ts.
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
title: "When it's unclear who wrote a line in Claude's transcript, trail counts it as not typed by the person"
author: Anirudhkumar-nanonets
date: 2026-11-17
branch: claude/fix-save-learning-prompts-84888d
cost: { minutes: 1, tokens: 10958 }
id: l-6b0c32a7
scope: repo
status: active
src: agent
touches:
- "src/trace/claude.ts#candidateText"
- "src/trace/claude.ts#ownText"
- "src/claude/note-signals.ts#typed"
---

## Decided
- Claude Code keeps adding lines to the person's slot in its transcript that the person never typed: Desktop's status block before each message, the compaction summary, messages from other sessions, artifact comments, prompts queued while Claude was busy. The format isn't documented as stable, so expect more of these.
- trail counts a line as the person's only when it is clearly theirs, and stays quiet when unsure. A missed save ask costs one learning. A false one ("The user corrected you" quoting a compaction summary) makes people stop trusting every later ask.
- One filter decides this for every learning path. No hook keeps its own copy: the Stop hook's own copy drifted, and that caused the missed Desktop corrections and the false compaction ask.

## Tried and ruled out
- A per-hook filter tuned to what that hook needs: it fell behind each time Claude Code added a new kind of line, and nobody noticed until a false or missed ask.

## Watch out
- A missing `origin` still counts as the person, because the CLI and older transcripts don't set one. So a new harness line with no `origin` and none of the skip flags gets through until its text shape is added to the not-typed patterns. When an ask quotes words the person never wrote, add that shape there, and add the real transcript line as a test.

In the code: src/trace/claude.ts `candidateText` (the skip flags `isMeta`, `isSidechain`, `isCompactSummary`, `isVisibleInTranscriptOnly`, and `origin.kind` must be `human` or absent), `ownText` (`WRAPPED`, `NOT_TYPED`, `ARTIFACT_COMMENT`), `typedText`; src/claude/note-signals.ts `typed` calls it; tests in test/trace-typed.test.ts and test/trail-note-ask.test.ts.
1 change: 1 addition & 0 deletions TELEMETRY.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ The events:
| `brain_signup_opened` | `mode` (`terminal`/`agent`/`nudge`), and for a nudge `command` (`ask`/`note`/`check`) and `wording` (`share`/`learned`) | A trail command hands the agent a sign-in link to pass on (at most once a session) |
| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`bad_callback`/`stopped`, and for an agent-run push `agent_link_opened`/`still_waiting`/`expired`/`unsupported`), `mode` (`terminal`/`agent`/`nudge`), `duration_bucket` | That handoff ends, one way or the other: for an agent-run push, each of its runs; for a nudge, each background wait for the sign-in (`linked`/`timed_out`/`expired`/`unsupported`) |
| `note_saved` | `has_cost` (`true`/`false`), `touches_bucket` (how many files the learning is about, bucketed), `scope` (`repo`/`personal`), `into` (`new`, or `session` when it went into the learning this session already saved) | `trail note` saves a learning, in the repo's `.trail/` or on this machine. The title, the text and the paths are never sent |
| `note_asked` | `kind` (`fixed`/`corrected`/`undone`/`chose`/`overrode`/`shipped`/`explored`: what made trail ask), `saved` (`repo`/`personal`/`no`) | trail's Stop hook asked Claude Code to save a learning; sent on the stop after, with whether one was saved. The conversation and the learning are never sent |
| `repo_seen` | `trail_committed` (`true`/`false`), `learnings_bucket`, `workspace` (`true`/`false`) | Once a day per repo, when a Claude Code session starts in a repo trail runs in. The repo's name and paths are never sent; it's identified only by the random `repo_id` every event carries |
| `learnings_committed` | `added_bucket`, `total_bucket` (learnings committed on `HEAD`, bucketed), `first_look` (`true`/`false`) | A Claude Code session starts in a repo trail runs in and more learnings are committed there than at the last session. Their names and text are never sent |
| `cold_start` | `source` (`sessions`/`reviews`/`memory`/`keep`), `outcome` (`found`/`none_found`/`none_anchored`/`no_sessions`/`no_reviews`/`no_gh`/`no_claude`/`not_signed_in`/`not_installed`/`timed_out`/`refused`/`failed`/`cancelled`/`kept`), `sessions_bucket` (sessions) or `reviews_bucket` (merged PRs with a reviewer's comment; reviews), `offered_bucket`, `filtered_bucket` (review findings left out for naming no code), `picked_bucket` (how many it saved: the ones the person kept), `team_offered_bucket`, `team_picked_bucket` (of those, the ones for `.trail/learnings/`; memory), `offered_skills`, `offered_always_follow`, `offered_learnings` (what the list showed, by kind: `0`/`1`/`2`/`3`/`4`/`5`/`6+`), `kept_skills`, `kept_always_follow`, `kept_learnings` (of those, the ones you kept; `outcome: kept`), `duration_bucket`, `model` | `trail init` reads your past Claude Code sessions in the repo, once, for things you told Claude on more than one day, and the review comments on the repo's last 50 merged PRs, once, for things reviewers flagged on more than one PR, and the notes Claude Code keeps about the repo on this machine (`source: memory`, no model), and offers them to you as learnings. It saves only the ones you keep, on its list or later with `trail keep` (`source: keep`). The reviews are fetched with your own `gh` (`no_gh` when it isn't installed or signed in) and the reading is done by your own Claude Code; your messages, the comments and what it found are never sent to trail |
Expand Down
2 changes: 1 addition & 1 deletion src/claude/format.ts
Original file line number Diff line number Diff line change
Expand Up @@ -414,7 +414,7 @@ export function teamNotesDirective(notes: number | NoteCounts, kept = total(note
: '';
return (
read +
`Save a learning when the session finds what the code can't tell the next person: a bug's cause after failed attempts, an approach dropped and why, a choice and why, or the user correcting how something is done here. \`${cmd('graft note')} --title "<the decision in plain words a teammate understands, no file names>"\` with the text on stdin, under ## Decided, ## Tried and ruled out and ## Watch out, giving the why. Put files, commands and values in the body under "In the code:". Never for setting up trail, status, or what the diff shows. A summary, never a transcript, and nothing secret. A learning is added to this repo unless it's about how this user likes to work or their own machine: then add --personal and it stays just with them. A learning is followed by default and the user can say otherwise in the moment; only when the user says it must hold even if someone asks otherwise, add --always-follow. One added to this repo goes in .trail/learnings/; commit it with the change so your teammates' Claude starts from it. Close your reply with the line ${cmd('graft note')} prints for it: for one added to this repo, the one for whether it's committed by then (check with git status --porcelain .trail/learnings).\n` +
`Save a learning when the session finds what the code can't tell the next person: a bug's cause after failed attempts, an approach dropped and why, a choice and why, or the user correcting how something is done here. \`${cmd('graft note')} --title "<the decision in plain words a teammate understands, no file names>"\` with the text on stdin, under ## Decided, ## Tried and ruled out and ## Watch out, giving the why. Put files, commands and values in the body under "In the code:". Never for setting up trail, status, or what the diff shows. A summary, never a transcript, and nothing secret. A learning is added to this repo unless it's about how this user likes to work, their own machine, or business, growth, sign-up, pricing or competitor reasoning or internal numbers: then add --personal and it stays just with them, even if you also keep your own copy. A learning is followed by default and the user can say otherwise in the moment; only when the user says it must hold even if someone asks otherwise, add --always-follow. One added to this repo goes in .trail/learnings/; commit it with the change so your teammates' Claude starts from it. Close your reply with the line ${cmd('graft note')} prints for it: for one added to this repo, the one for whether it's committed by then (check with git status --porcelain .trail/learnings).\n` +
(brand() === 'trail'
? `When the work is ready for review, run \`trail check\` before you commit it, push the branch or open a PR: it compares the branch's changes, committed or not, with this repo's learnings and yours, and exits 1 on a conflict. Fix the conflict, or say why the change is right anyway in the commit message or PR description. If the user asks you to save what changed, save it as a new learning that replaces the old one (\`trail note --replaces <id>\`). A replacement saved on this branch leaves the conflict in place until it's merged, so still say why in the PR. Never edit an existing learning, yours or a teammate's.\n`
: '')
Expand Down
Loading
Loading