shift-notes

Name: shift-notes
Author: Archive228

712stars129forks

How to install shift-notes?

archive228/loopkit/shift-notes

$npx -y skills add Archive228/loopkit --skill shift-notes

Installs into the current project.

Summary

Write and read the between-session handoff file so a fresh agent with no memory can pick up where the last one stopped without re-deriving context. Structured prose, not JSON — the model writes prose better.

Files · 1

View on GitHub

SKILL.md

1	# Shift Notes
2
3	The hard problem in long-running agents is not doing work in one session — it's bridging the context gap between sessions. Every fresh agent starts with zero memory. If it has to reconstruct project state from the code, it burns 5-10 minutes and a chunk of context before writing a line. If it has a well-shaped handoff file, that drops to 30-60 seconds.
4
5	That handoff file is `claude-progress.txt` (or equivalent). Prose, not JSON. The model writes prose more naturally, and the read is cheap.
6
7	## The format — write into this shape
8
9	```
10	# Project: <name>
11	# Last updated: <ISO timestamp> by session <id>
12
13	## What's done
14	- <feature> [feature-list index: N]
15	- ...
16
17	## What's in progress
18	- <feature> [feature-list index: N]
19	Status: <one paragraph — what works, what doesn't>
20	Files touched this session: <list>
21	Known open issues: <list>
22
23	## What's next (recommended)
24	- <feature> [feature-list index: N]
25	Reason: <why this one>
26
27	## Notes for the next session
28	<free-form prose: gotchas, flaky tests, environment quirks>
29	```
30
31	Enforced softly by the prompt, not by validation. Free text is the point — the notes section is where the previous shift warns the next one about the thing that isn't captured anywhere else.
32
33	## Writing the notes — at end of session
34
35	- Move the completed feature from "in progress" to "done".
36	- Recommend the next feature in "what's next" with a one-line reason (unblocks-N, low-risk, prerequisite-for-M).
37	- Notes-for-next-session is the highest-leverage field. Use it for: flaky tests you hit, dependencies that surprised you, spec ambiguities you resolved one way (so the next agent doesn't re-litigate), env vars that need to be set.
38	- Do not delete "done" entries. They're audit trail. If the section gets long, that's a signal to compact the whole notes file at v0.2 milestones, not to prune mid-project.
39
40	## Reading the notes — at start of session
41
42	- Read the whole file. It's small.
43	- If shift notes and git log disagree, trust the git log. The notes can be truncated by a crashed session; the log can't. This is a load-bearing rule.
44	- Cross-reference "what's done" against the feature list. If the notes claim done but the feature list says not-done, run `broken-window-check`.
45	- Pick work from "what's next" unless it's stale (a new session already picked it).
46
47	## Red flags
48
49	- Notes rewritten every session from scratch. Lose history, lose audit trail. Append and edit in place, don't overwrite.
50	- "What's done" section grows unboundedly. Fine up to ~40 entries. Past that, compact by feature milestone.
51	- Ambiguous "in progress" prose. The next session will misread "the button is wired but the state doesn't refresh" as "done" if you write "button works". Be precise about what fails.
52	- Notes drift out of sync with the feature list. Feature list is source of truth for pass/fail state; notes are the prose gloss. When they disagree, the list wins.
53	- JSON handoff file. Tried and abandoned — the model wrote shorter, less useful notes when forced into JSON. Prose wins for prose.
54
55	## What NOT to put in the notes
56
57	- Full file contents. Reference paths, not blobs.
58	- Chain-of-thought for the session. Compact it into a status line.
59	- Anything that belongs in the feature list (pass/fail state) or in git (what changed).
60
61	## Pairs with
62
63	- `broken-window-check` — reads the "what's done" list to know what to smoke-test.
64	- `spec-first` — the spec is the contract; the notes are the ledger against it.
65	- `context-budget` — the notes are the compact recap the context-budget skill wants.
66
67	The shift-notes file is the memory of the project. Treat it as load-bearing.

People who liked this also viewed

6 picks

Type

shift-notes

712stars129forks

View on GitHub

How to install shift-notes?

archive228/loopkit/shift-notes

$npx -y skills add Archive228/loopkit --skill shift-notes

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Shift Notes
2
3	The hard problem in long-running agents is not doing work in one session — it's bridging the context gap between sessions. Every fresh agent starts with zero memory. If it has to reconstruct project state from the code, it burns 5-10 minutes and a chunk of context before writing a line. If it has a well-shaped handoff file, that drops to 30-60 seconds.
4
5	That handoff file is `claude-progress.txt` (or equivalent). Prose, not JSON. The model writes prose more naturally, and the read is cheap.
6
7	## The format — write into this shape
8
9	```
10	# Project: <name>
11	# Last updated: <ISO timestamp> by session <id>
12
13	## What's done
14	- <feature> [feature-list index: N]
15	- ...
16
17	## What's in progress
18	- <feature> [feature-list index: N]
19	Status: <one paragraph — what works, what doesn't>
20	Files touched this session: <list>
21	Known open issues: <list>
22
23	## What's next (recommended)
24	- <feature> [feature-list index: N]
25	Reason: <why this one>
26
27	## Notes for the next session
28	<free-form prose: gotchas, flaky tests, environment quirks>
29	```
30
31	Enforced softly by the prompt, not by validation. Free text is the point — the notes section is where the previous shift warns the next one about the thing that isn't captured anywhere else.
32
33	## Writing the notes — at end of session
34
35	- Move the completed feature from "in progress" to "done".
36	- Recommend the next feature in "what's next" with a one-line reason (unblocks-N, low-risk, prerequisite-for-M).
37	- Notes-for-next-session is the highest-leverage field. Use it for: flaky tests you hit, dependencies that surprised you, spec ambiguities you resolved one way (so the next agent doesn't re-litigate), env vars that need to be set.
38	- Do not delete "done" entries. They're audit trail. If the section gets long, that's a signal to compact the whole notes file at v0.2 milestones, not to prune mid-project.
39
40	## Reading the notes — at start of session
41
42	- Read the whole file. It's small.
43	- If shift notes and git log disagree, trust the git log. The notes can be truncated by a crashed session; the log can't. This is a load-bearing rule.
44	- Cross-reference "what's done" against the feature list. If the notes claim done but the feature list says not-done, run `broken-window-check`.
45	- Pick work from "what's next" unless it's stale (a new session already picked it).
46
47	## Red flags
48
49	- Notes rewritten every session from scratch. Lose history, lose audit trail. Append and edit in place, don't overwrite.
50	- "What's done" section grows unboundedly. Fine up to ~40 entries. Past that, compact by feature milestone.
51	- Ambiguous "in progress" prose. The next session will misread "the button is wired but the state doesn't refresh" as "done" if you write "button works". Be precise about what fails.
52	- Notes drift out of sync with the feature list. Feature list is source of truth for pass/fail state; notes are the prose gloss. When they disagree, the list wins.
53	- JSON handoff file. Tried and abandoned — the model wrote shorter, less useful notes when forced into JSON. Prose wins for prose.
54
55	## What NOT to put in the notes
56
57	- Full file contents. Reference paths, not blobs.
58	- Chain-of-thought for the session. Compact it into a status line.
59	- Anything that belongs in the feature list (pass/fail state) or in git (what changed).
60
61	## Pairs with
62
63	- `broken-window-check` — reads the "what's done" list to know what to smoke-test.
64	- `spec-first` — the spec is the contract; the notes are the ledger against it.
65	- `context-budget` — the notes are the compact recap the context-budget skill wants.
66
67	The shift-notes file is the memory of the project. Treat it as load-bearing.

People who liked this also viewed

6 picks

Type