session-state-management

Name: session-state-management
Author: UnpaidAttention

84stars18forks

How to install session-state-management?

unpaidattention/fable5-methodology/session-state-management

$npx -y skills add UnpaidAttention/fable5-methodology --skill session-state-management

Installs into the current project.

Summary

Stay coherent across a long agentic session by keeping the task's state on disk — a WORKING_NOTES.md with the task, plan, decisions, and status — updated at every milestone and re-read after any context loss. Trigger this at the start of any task likely to exceed ~30 minutes or ~

Files · 1

View on GitHub

SKILL.md

1	# Session State Management
2
3	Your context window is unreliable storage: it compacts, truncates, and ends. Disk does not.
4	Anything you'd be sorry to lose goes in a file, at the moment you'd be sorry to lose it.
5
6	## Step 1: Create WORKING_NOTES.md at task start
7
8	Location: the session scratchpad directory, or the repo root if the user's workflow expects
9	it (never commit it unless asked). Structure — create all sections immediately, even empty:
10
11	```markdown
12	# WORKING NOTES — <task title>
13
14	## Task (verbatim requirements)
15	<paste the user's actual requirements and process instructions — not your paraphrase;
16	paraphrases drift and the original message may scroll out of context>
17
18	## Plan
19	<ordered steps, checked off as done>
20
21	## Decisions
22	<one line each: what was decided, and why — "IDs are ULIDs not UUIDs: sortable, spec §3">
23
24	## Status
25	<done / in progress / blocked, per step>
26
27	## Next action
28	<the exact next command or edit, written for a cold reader>
29
30	## Assumptions & open questions
31	```
32
33	## Step 2: Update triggers (write at the moment, not "later")
34
35	Update the file when ANY of these occurs:
36	1. A plan step completes or a milestone verifies → check it off, update Status.
37	2. A decision is made that later work must honor (naming, format, interface shape) → Decisions.
38	3. The plan changes direction → rewrite Plan, note why in Decisions.
39	4. You're about to do anything risky or slow (migration, big refactor step, long build) →
40	record Next action FIRST, so a crash mid-operation leaves a resume point.
41	5. Roughly every 30–45 minutes of work with no other trigger → refresh Status and Next action.
42
43	## Step 3: Re-read triggers
44
45	Re-read WORKING_NOTES.md — fully, not from memory — when:
46	1. A context-compaction notice appears, or a session resumes.
47	2. You're unsure what was already decided or already tried.
48	3. You're about to start a new plan step (glance at Decisions so step 9 honors what step 2 chose).
49	4. Before writing the final delivery message (the Task section is the requirements checklist).
50
51	Rule: after any suspected context loss, trust the file over your recollection wherever
52	they disagree. The file was written at the moment of knowledge; your recollection is a
53	reconstruction.
54
55	## Step 4: Split across sessions instead of overextending one
56
57	End the session at a natural boundary (a checkpoint, a completed unit) rather than pushing on,
58	when ANY of:
59	1. Remaining work is clearly larger than what's been done and quality is already degrading —
60	see the signs below.
61	2. Verification has failed 3+ times on the same criterion (grinding, not progressing).
62	3. Degradation signs: repeating searches you already ran, re-deriving established facts,
63	contradicting the Decisions list, or instructions from the original request coming as a
64	surprise on re-read.
65
66	To split: finish the current unit to a verified state, update WORKING_NOTES.md so the Next
67	action block is executable cold ("run `pytest tests/test_sync.py`, then implement step 5:
68	retry logic in `sync.py:120` per Decision 4"), and tell the user where things stand and what
69	the next session picks up.
70
71	## Worked example
72
73	Mid-task, a compaction notice appears during an 8-step API migration.
74
75	- Without this skill: you continue from a summarized memory, re-implement the error envelope
76	you already built (differently), and step 7 contradicts the pagination decision from step 2.
77	- With it: you re-read WORKING_NOTES.md — Decisions says "error envelope: `{error: {code,
78	message}}`, pagination: cursor-based, decided step 2"; Status shows steps 1–5 verified,
79	step 6 in progress with next action "wire cursor into `/orders` handler". You resume in two
80	minutes with zero re-derivation and no drift.
81
82	## Done when
83
84	WORKING_NOTES.md exists from task start and its Status/Next-action sections would let a cold
85	model resume correctly right now; every cross-cutting decision made this session appears in
86	Decisions; and at delivery, the verbatim Task section was used as the final requirements
87	checklist.

People who liked this also viewed

6 picks

Type

session-state-management

84stars18forks

View on GitHub

How to install session-state-management?

unpaidattention/fable5-methodology/session-state-management

$npx -y skills add UnpaidAttention/fable5-methodology --skill session-state-management

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Session State Management
2
3	Your context window is unreliable storage: it compacts, truncates, and ends. Disk does not.
4	Anything you'd be sorry to lose goes in a file, at the moment you'd be sorry to lose it.
5
6	## Step 1: Create WORKING_NOTES.md at task start
7
8	Location: the session scratchpad directory, or the repo root if the user's workflow expects
9	it (never commit it unless asked). Structure — create all sections immediately, even empty:
10
11	```markdown
12	# WORKING NOTES — <task title>
13
14	## Task (verbatim requirements)
15	<paste the user's actual requirements and process instructions — not your paraphrase;
16	paraphrases drift and the original message may scroll out of context>
17
18	## Plan
19	<ordered steps, checked off as done>
20
21	## Decisions
22	<one line each: what was decided, and why — "IDs are ULIDs not UUIDs: sortable, spec §3">
23
24	## Status
25	<done / in progress / blocked, per step>
26
27	## Next action
28	<the exact next command or edit, written for a cold reader>
29
30	## Assumptions & open questions
31	```
32
33	## Step 2: Update triggers (write at the moment, not "later")
34
35	Update the file when ANY of these occurs:
36	1. A plan step completes or a milestone verifies → check it off, update Status.
37	2. A decision is made that later work must honor (naming, format, interface shape) → Decisions.
38	3. The plan changes direction → rewrite Plan, note why in Decisions.
39	4. You're about to do anything risky or slow (migration, big refactor step, long build) →
40	record Next action FIRST, so a crash mid-operation leaves a resume point.
41	5. Roughly every 30–45 minutes of work with no other trigger → refresh Status and Next action.
42
43	## Step 3: Re-read triggers
44
45	Re-read WORKING_NOTES.md — fully, not from memory — when:
46	1. A context-compaction notice appears, or a session resumes.
47	2. You're unsure what was already decided or already tried.
48	3. You're about to start a new plan step (glance at Decisions so step 9 honors what step 2 chose).
49	4. Before writing the final delivery message (the Task section is the requirements checklist).
50
51	Rule: after any suspected context loss, trust the file over your recollection wherever
52	they disagree. The file was written at the moment of knowledge; your recollection is a
53	reconstruction.
54
55	## Step 4: Split across sessions instead of overextending one
56
57	End the session at a natural boundary (a checkpoint, a completed unit) rather than pushing on,
58	when ANY of:
59	1. Remaining work is clearly larger than what's been done and quality is already degrading —
60	see the signs below.
61	2. Verification has failed 3+ times on the same criterion (grinding, not progressing).
62	3. Degradation signs: repeating searches you already ran, re-deriving established facts,
63	contradicting the Decisions list, or instructions from the original request coming as a
64	surprise on re-read.
65
66	To split: finish the current unit to a verified state, update WORKING_NOTES.md so the Next
67	action block is executable cold ("run `pytest tests/test_sync.py`, then implement step 5:
68	retry logic in `sync.py:120` per Decision 4"), and tell the user where things stand and what
69	the next session picks up.
70
71	## Worked example
72
73	Mid-task, a compaction notice appears during an 8-step API migration.
74
75	- Without this skill: you continue from a summarized memory, re-implement the error envelope
76	you already built (differently), and step 7 contradicts the pagination decision from step 2.
77	- With it: you re-read WORKING_NOTES.md — Decisions says "error envelope: `{error: {code,
78	message}}`, pagination: cursor-based, decided step 2"; Status shows steps 1–5 verified,
79	step 6 in progress with next action "wire cursor into `/orders` handler". You resume in two
80	minutes with zero re-derivation and no drift.
81
82	## Done when
83
84	WORKING_NOTES.md exists from task start and its Status/Next-action sections would let a cold
85	model resume correctly right now; every cross-cutting decision made this session appears in
86	Decisions; and at delivery, the verbatim Task section was used as the final requirements
87	checklist.

People who liked this also viewed

6 picks

Type