|
| 1 | +# Session protocol + audit checklist — shared template |
| 2 | + |
| 3 | +This file is the canonical source for the "🔁 Session protocol" + |
| 4 | +"🔍 Audit checklist" sections that appear at the top of every |
| 5 | +Simtabi project's `docs/SPEC.md`. SPEC §5 issue C5 said to factor |
| 6 | +out this duplication; the template lives here in `ai-config-kit` |
| 7 | +(the project where the pattern originated) and the other repos |
| 8 | +reference it. |
| 9 | + |
| 10 | +When a third Simtabi project adopts this pattern, copy the two |
| 11 | +sections below into its SPEC.md unchanged (the project name is |
| 12 | +the only variable). When the protocol changes, update this file |
| 13 | +first, then propagate to consumer SPECs: |
| 14 | + |
| 15 | +- `simtabi/ai-config-kit/docs/SPEC.md` |
| 16 | +- `simtabi/get-installer/docs/SPEC.md` |
| 17 | +- _add new consumers here as they appear_ |
| 18 | + |
| 19 | +A future cleanup could move this to `simtabi/.github/` as an |
| 20 | +org-default; for now keeping it in this repo is fine since the |
| 21 | +ecosystem is small. |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## 🔁 Session protocol (read before everything else) |
| 26 | + |
| 27 | +**Session start**: |
| 28 | + |
| 29 | +1. Read this SPEC end-to-end. |
| 30 | +2. Run the audit checklist below (5-line summary at the top of your reply). |
| 31 | +3. Read `STATUS.md` if present + `~/.claude/projects/<slug>/memory/MEMORY.md` |
| 32 | + + the latest `CHANGELOG.md` entry. |
| 33 | +4. Restate the user's goal in one sentence before any tool call. |
| 34 | + |
| 35 | +**During the work**: |
| 36 | + |
| 37 | +5. **Hallucination guard**: every claim about the codebase comes |
| 38 | + from a live `Read` / `Grep` / shell call. Memory tells you what was |
| 39 | + true when written, not what's true now. Cite `path:line` where |
| 40 | + possible. Phrases that signal you're guessing: "typically", |
| 41 | + "usually", "I believe", "around line ~", round numbers, paraphrases |
| 42 | + of code you haven't opened. |
| 43 | + |
| 44 | +6. **Track progress**: `TaskCreate` / `TaskUpdate` for anything |
| 45 | + beyond 3 steps. Mark `in_progress` before you start; `completed` |
| 46 | + the moment it's done, not in a batch. |
| 47 | + |
| 48 | +7. **Watch for regressions**: re-run the audit checklist after every |
| 49 | + non-trivial edit; don't accumulate a "tests-at-the-end" debt. |
| 50 | + |
| 51 | +8. **Log failures**: when a step fails, surface it in your reply |
| 52 | + immediately: what failed, what you tried, what you'll try next. |
| 53 | + |
| 54 | +9. **Research before guessing**: `WebFetch` the official docs site |
| 55 | + first, project README + spec second, reputable blogs third. Skip: |
| 56 | + Medium content farms, AI-generated blog spam, paywalled pages. |
| 57 | + |
| 58 | +10. **Clarifying questions**: when the request is ambiguous and the |
| 59 | + wrong path costs > 5 minutes to undo, ask once with a numbered |
| 60 | + options list. Not Socratic chains. |
| 61 | + |
| 62 | +**Session end**: |
| 63 | + |
| 64 | +11. **Self-improvement loop**: suggest SPEC updates (new findings → |
| 65 | + §5; finished phases → `[x]`), prompt updates (this section), test |
| 66 | + gaps you noticed. |
| 67 | + |
| 68 | +12. **Hand-off summary**: last paragraph: what changed (paths), what's |
| 69 | + still open (issue ids), what the next agent picks up first. |
| 70 | + |
| 71 | +--- |
| 72 | + |
| 73 | +## 🔍 Audit checklist: run this FIRST every session |
| 74 | + |
| 75 | +Before writing code, run a status sweep and report the findings inline. |
| 76 | + |
| 77 | +1. **`pytest -q`**: must be green. |
| 78 | +2. **`ruff check src tests`**: must be clean. |
| 79 | +3. **`mypy --strict <src-package>`**: must be clean. |
| 80 | +4. **CLI surface check**: `python -m <package> --help` should list |
| 81 | + every subcommand documented in `docs/tools/<package>.md`. |
| 82 | +5. **README authority check**: exactly ONE `README.md` at the repo |
| 83 | + root + project name + `pip install` line accurate to pyproject.toml. |
| 84 | +6. **CHANGELOG check**: `[Unreleased]` section exists; the most |
| 85 | + recent dated entry matches the latest tag. |
| 86 | +7. **External-URL drift check**: any URL pinned anywhere in the repo |
| 87 | + (badges, schema $ref, doc links) responds 200/3xx. If you can't |
| 88 | + reach the network, say so. |
| 89 | + |
| 90 | +The 5-line summary at the top of every reply has the form: |
| 91 | + |
| 92 | +``` |
| 93 | +audit: tests=PASS lint=PASS types=PASS docs=PASS urls=N/A |
| 94 | +queue: <one-line description of what I'm about to do> |
| 95 | +``` |
| 96 | + |
| 97 | +Anything that fails → fix BEFORE the user-facing work, OR flag |
| 98 | +explicitly with "blocked on X" and propose a path forward. |
| 99 | + |
| 100 | +--- |
| 101 | + |
| 102 | +_The two sections above are kept in lock-step across every |
| 103 | +consuming SPEC.md. Source of truth: this file._ |
0 commit comments