agentleFS
scottcrosby-securebinescottcrosby-securebine/doctrine-skills/skills/doctrine-resume/SKILL.md

doctrine-resume

Skill0 starsChanged 4 days agoMITView on GitHub

Use when the user asks to load memory, resume the session, restore state, or pick up where the last session left off. Reads SESSION_MEMORY.md and the handoff its kickoff names, loads the doctrine when a doctrine phase is open, and reports drift. State only, no codebase tour.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If none exists, say so and stop: there is nothing to resume, and doctrine-primer is the right command.

    line 18
  2. Very specific:

    Read Gotchas even though the report below only echoes them on request.

    line 24
  3. Distinctive:

    Before any drift check, read the kickoff's first line.

    line 30
  4. Distinctive:

    When the record reads Open or Blocked, your next actions load these skills by name (on Claude Code through its skill-loading tool.

    line 51
  5. Distinctive:

    When the record reads anything else (Exited, Stopped, Shipped, Unable, or no state line at all), invoke neither, whatever the kickoff says.

    line 61
  6. Very specific:

    When no record was read, because the handoff names none or its path resolves nowhere (say which in the Handoff line), fall back to the …

    line 64
  7. Very specific:

    Do not take it again. The Handoff line says first action: done.

    line 100
  8. Very specific:

    If gh errors, say so once and continue git-only.

    line 124
  9. Distinctive:

    If the column is named for a retired tracker, its ids are dead: report them as unhydratable and suggest migrating them, rather than …

    line 162
  10. Very specific:

    Add nothing beyond this skeleton — the quoted sections run as long as they run, and truncating a verbatim Resume or Kickoff defeats the …

    line 184
  11. Very specific:

    Every drift check has run, every bare-#N cell is hydrated and every skipped cell named, the kickoff is quoted or its absence flagged, its …

    line 220

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Doctrine Resume — warm resume

Restore session state and report drift. This is the cheap path: state only, no codebase tour. Use doctrine-primer when the agent needs the project explained.

1. Find and read saved state

ls the repo root first — do not assume the filename. The usual name is SESSION_MEMORY.md, but a project may use another, and some carry several scoped variants. If exactly one exists, read it. If several exist, read the unqualified one and name the others rather than merging them.

If none exists, say so and stop: there is nothing to resume, and doctrine-primer is the right command.

Parse every section: Resume, Active Work, Git State, Runtime, Gotchas, and Next Session Kickoff.

Read Gotchas even though the report below only echoes them on request. Step 5 can hand off to doctrine-backup, which carries forward what it was told — anything you skipped here is a line you may help delete.

1b. Act on the kickoff's first line

Before any drift check, read the kickoff's first line. If it names a handoff path, read that file in full now, by that path — never the newest file in a directory, which on a clone is any of them.

Then read the record the handoff's record: header line names (doctrine step 5 gives the header lines). Resolve its path by taking the first of these that exists: the path as written if absolute, else relative to the repo root, else relative to the repo root's parent directory, which is where a sibling repo's path such as <other-repo>/.doctrine/records/<file>.md lands. In the record, take its last state line (a line whose text starts State:, in any case, bare, bold or as a list item) and its last wrapper: line, else the handoff header's wrapper: line (doctrine step 1; drop a doctrine: prefix and a trailing period or comma from the value). What the record reads is the first word after State: on that line, bold and trailing period ignored. The record is the authority on whether a phase is open, never the kickoff: when the record's state and the kickoff's state: disagree (the record reads Open or Blocked and the kickoff reads anything but open, or the record reads anything else and the kickoff reads open), name the mismatch in the Handoff line. Facts a restore hook put in this session's context are a hint and never outrank the record.

When the record reads Open or Blocked, your next actions load these skills by name (on Claude Code through its skill-loading tool; on Codex by reading each skill's SKILL.md from your skill list), in this order: doctrine:<wrapper> (for example doctrine:doctrine-code), then doctrine:doctrine unless the wrapper already had you invoke it. With wrapper: none, or no wrapper line in the record or the handoff header, invoke only doctrine:doctrine. Nothing comes before them except step 1's ls and the reads this step and step 1 already made: no drift check, no git or gh, no other file read and no other directory listing, even of the directory the handoff sits in. When it reads Blocked, also name the open question in the Handoff line: the record's last question: <id> opened line with no later question: <id> answered line for the same id, else the state line's own text. When the record reads anything else (Exited, Stopped, Shipped, Unable, or no state line at all), invoke neither, whatever the kickoff says.

When no record was read, because the handoff names none or its path resolves nowhere (say which in the Handoff line), fall back to the kickoff: if the kickoff line's state: is open (case-insensitive), load the doctrine:doctrine skill by name before any other call: the handoff describes the doctrine as it stood when it was written, and a session that only reads about the doctrine never loads it. open means a doctrine phase is open; any other value means do not. If a skill named in this step is not installed, say so in the Handoff line and continue; the handoff's Suggested skills section names what to load instead. The handoff is a dated snapshot and the memory file is rewritten at every backup: where the two disagree, the memory file's Kickoff is current and the handoff is history, and the Handoff line says so. A kickoff with no such line predates this rule: quote it as before and say the line is missing. A named handoff that does not exist on disk is drift, reported in step 4, not silence.

Two more checks follow the invocations above, or come first when none was due, whenever the kickoff names a handoff that exists on disk.

Interrupted backup. The backup that should have carried the current handoff never landed when the memory file is tracked and git diff HEAD -- <memory file> changes the handoff path on its kickoff line, or it is untracked and not ignored (git ls-files --others --exclude-standard -- <memory file> lists it), or a handoff under docs/handoffs/ names the kickoff's handoff in its supersedes: line (that newer handoff is the one to back up: from here on, its header is the one this step's record read and invocations follow, so re-run those on it where they read the older one). A dirty memory file whose kickoff line is unchanged, and an ignored one, are not this case. The Handoff line says interrupted: handoff written, backup not committed, and step 5 finishes that backup. Never run doctrine-handoff for this case, since a second handoff would head the supersedes: chain beside this one.

First action. The handoff's section 5, Do this first, is one action; in the interrupted case above it is the section 5 of the handoff found interrupted. Settle whether it already ran before anyone takes it:

  • Done: a line in the memory file's Resume or in the record names it done. Do not take it again. The Handoff line says first action: done.
  • Ambiguous: no such line, but the tree or the record shows its effect (the commit it names exists, the file it names exists, the <out>.result file of the check it launches exists). Take it zero times, whether or not auto-cycle is on. Append - auto-cycle paused: first action ambiguous: <the section 5 sentence, verbatim> to the record read above, placed as doctrine-backup's rule "Under auto-cycle, a question pauses the run" places its line, say first action: ambiguous, paused in the Handoff line, and end the turn after step 4's report. With no record read above, append nothing and ask the user whether it ran.
  • Otherwise it is due, and the Handoff line says first action: due.

2. Check drift

Drift is any gap between what the file claims and what the repo shows. Batch:

  • git status -sb — branch and ahead/behind, against the saved Git State
  • git status --short | grep -v '^??' — tracked-only, the unit the memory file records; a raw listing counts untracked tooling dirs and fakes drift
  • git log --oneline -5 — what landed since the file was written
  • gh pr list --state open
  • gh workflow list, then the build/publish workflow's gh run list --workflow "<name>" --limit 3 --json headSha,conclusion

If gh errors, say so once and continue git-only. If gh workflow list succeeds but is empty, the repo has no CI — say that rather than reporting a failed build. An empty conclusion means the run is still going: report "running".

Trust the repo over the file. Name each mismatch specifically — "memory says 4b172f9b, HEAD is 8b36d9f7" beats "state has drifted."

The backup's own commit is not drift. A backup records the SHA before it commits, so its commit sits one past the Git State line. When git merge-base --is-ancestor <recorded sha> HEAD succeeds, git rev-list --count <recorded sha>..HEAD prints 1, and git show --name-only --format=%s HEAD prints a subject starting docs(session): and only paths the pathspec of doctrine-backup step 6's commit line may name, report no drift for that commit, nor for an ahead count that differs from the saved one by that commit alone.

A green build usually means artifacts were published, not that anything was deployed. Treat a "deployed" claim as unverified unless the repo documents a deploy check and you run it.

3. Hydrate active work

Find the Active Work table's tracker column — commonly Issue, but it may carry another name. Hydrate only cells that are a bare #N or N:

gh issue view <N> --json title,state --jq '"\(.state)  \(.title)"'

Skip everything else, and say what you skipped rather than silently passing:

  • a placeholder — either — (em dash) or an ASCII -
  • several ids in one cell
  • a legacy tracker id such as repo-a1b2 — gh issue view errors on these
  • a cross-repo reference such as otherrepo #492. That number belongs to a different repo; running it here resolves against the wrong one and either errors or, worse, returns an unrelated issue

If the column is named for a retired tracker, its ids are dead: report them as unhydratable and suggest migrating them, rather than guessing at counterparts.

An issue the file calls open but gh calls closed is drift — report it.

4. Report

## Session Restored

**Resume**: [the file's Resume, verbatim]

**Kickoff**: [the file's Next Session Kickoff, verbatim — or "absent" if missing]

**Handoff**: [path read | none named | named but missing] · record [<path>, last state line quoted | none named | not found] · doctrine [invoked, with the skills named | not open | not installed] [· mismatch with the kickoff's state] [· open question] [· interrupted: handoff written, backup not committed] [· first action: done | ambiguous, paused | due]

**Drift**: ✅ none | ⚠️ [specific mismatches, one per line]

**Active Work** (hydrated):
| Item | Issue | State | Key Files |

Add nothing beyond this skeleton — the quoted sections run as long as they run, and truncating a verbatim Resume or Kickoff defeats the point. Carry the file's Key Files column through unchanged; it is the next agent's only pointer into the code.

5. Resync on drift

In step 1b's interrupted case, do not ask: run doctrine-backup steps 3 to 6 on the handoff step 1b found interrupted, treated there as the handoff this run wrote, so the kickoff names it, with step 2's batch as its step 1 output, its step 2 run only where the kickoff line is unchanged, and as the previous memory file its step 5 hands the red team git show HEAD:<memory file> where HEAD holds it, else the file as it stands on disk where the kickoff line is unchanged, else none.

Otherwise, when the repo and the file disagree and auto-cycle is off, ask: "Memory is stale — resync it?" On yes, run doctrine-backup, which updates the file in place and carries forward Gotchas and any unresolved 🔴 row. That closes the loop so the next session starts from truth instead of inheriting the same stale file.

With auto-cycle on (doctrine step 5 defines when), neither ask nor pause: name the drift in step 4's report and in one prose line in the record's orchestrator-only part, and leave the resync to the backup the cycle's handoff runs.

6. Carry on under auto-cycle

With auto-cycle on (doctrine step 5 defines when), the report does not end the turn. Carry on with the phase in the same turn, under the wrapper step 1b invoked: take the first action where step 1b found it due, and otherwise continue from where the record and the handoff say the phase stands. Stop instead only where a rule already stops the run: step 1b's ambiguous first action, a Blocked record, and where doctrine step 5 (its pauses and the gauge's warning) or doctrine-backup ends the turn.

Done when

Every drift check has run, every bare-#N cell is hydrated and every skipped cell named, the kickoff is quoted or its absence flagged, its first line was acted on before anything but step 1b's interrupted-backup and first-action checks ran, and, with auto-cycle on, step 6 carried the phase on or stopped where it says.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.