admin
c30430c530
The four existing skills cover the product; nothing covered how work is reported. Two rules this project has paid for — check the artifact rather than the report, and do not state a claim more firmly than the evidence allows — lived only in the operator's head and in chat, where Claude Code never read them. - felhom-evidence five confidence tiers, artifact-over-report - felhom-diagnosis no hypothesis until a command has been seen red - felhom-plain-language ASD-STE100, two options, the re-pitch - felhom-handoff the note goes to a FILE, not the conversation - felhom-doc-authoring the pointer decides whether material is reached scripts/check_skills.py asserts what decides whether a skill is EVER reached: frontmatter parses, name == directory, description and body non-empty, under 150 lines, installed copy still samefile()s into the repo. install_skills.py globs and never reads the file, so a missing description installs perfectly and then silently never loads. It convicted on its first run: felhom-build-deploy is 179 lines. NOT trimmed here (pre-existing skills are out of scope, and trimming a deploy skill without exercising its commands is how a wrong command reaches a live host) — a named single-entry GRANDFATHERED exception, WARNed every run, R-394. A new skill over the limit is convicted. Red-proof run and seen failing: description removed from felhom-evidence -> exit 1, "frontmatter field 'description' is missing or empty". Restored, tree clean. skills/SOURCES.md records both MIT upstreams, that these are adaptations not copies, and the six pieces deliberately EXCLUDED with reasons. Register: R-392 (no architecture doc covers the two-AI workflow), R-393 (decision-log skill deferred, with the reason), R-394.
3.6 KiB
name, description
| name | description |
|---|---|
| felhom-handoff | How to end a Felhom session so the next one resumes instead of restarting, and how to pick one up. Triggers - "handoff", "pause safely", "I need to stop", "pick this up later", "take over from", "resume where we left off"; and whenever the context window is about to be compacted mid-task. Contains the stopping procedure, the handoff-note contents and path, and the pickup rules. |
Handoff
A session that ends without a note is a session the next one repeats.
1. Stopping
- Finish the current atomic step, or back out of it. Never stop mid-edit in a known-broken state. Half a rename is worse than neither half.
- Start nothing new. The urge to squeeze in one more small thing is what produces the broken middle state.
- Do not cross an irreversible line in order to pause. No deploy, no destructive operation, no data change gets rushed so the session can end tidily. Stopping before it is always allowed.
- Make the work durable. Commit outstanding edits as one clear
wip:commit onmain. If the tree is broken, say so in one line of the commit body — an unpushed change does not exist, and a broken tree that says it is broken costs the next session a minute instead of an hour.
2. The note
Write it to a file, not into the conversation. An in-context plan does not survive compaction, which is the exact moment it is needed.
Path: /tmp/felhom-handoff-<slug>.md
It contains:
- The goal — what this work is for, in one or two sentences.
- What was done, and what of it is verified — separately. Per
felhom-evidence, "done" and "proven" are different claims and the next session needs to know which is which. - Current state on disk — branch, commit, whether the tree is clean, what is running where.
- The next concrete action — one action, specific enough to start without a decision.
- Key paths — the files this work lives in.
- Gotchas — what was tried and did not work, so it is not tried twice.
Reference other artifacts by path rather than duplicating them. A spec, a REPORT.md, a commit
hash, a register row. A copied paragraph in the note becomes a second source that drifts from the
first, and the next session cannot tell which one is current.
Redact anything sensitive. No tokens, no passwords, no recovery codes, no private keys — the
same rule that applies to REPORT.md and every committed file applies here.
3. Picking up
A pickup is inheritance, not a restart.
Read the prior trail — the note, the REPORT.md, the commits, the register rows — and resist
re-deriving it. The earlier session already paid for reading the code and running the repros.
Redoing that work burns the context you need for the actual task, and it loses the independent check
that a second pair of eyes would have given.
Then reconstruct the state and continue:
- The tree — what is checked out, what is clean, what is unpushed.
- What landed — the commits, on the remote.
- What is open — the register rows, the note's next action.
- What was decided — and by whom, so a settled decision is not reopened by accident.
- Name the resume point out loud, then continue from it.
A "let me verify everything from scratch" pass is the tell that the trail is being treated as untrustworthy when it is authoritative.
One exception, and it is not optional. An inherited claim about the code is verified against
live source before it is acted on. The trail is authoritative about what was decided and what was
attempted; it is not authoritative about what the code currently says. That distinction, and the
reason for it, is felhom-evidence §6.