ai-agents-docs-of-record
Runbook for this repo's documents of record. Session logs, ADRs, retrospectives, Serena memories, per-issue handoffs, plus the templates, validators, naming rules, and house prose style that bind them. Use when you say `write the session log`, `create an ADR`, `fill the retro`, `save this to memory`, `which document of record`. Do NOT use for authoring skills (use `SkillForge`) or research write-ups (use `ai-agents-research-methodology`).
rjmurillo · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rjmurillo/ai-agents --skill ai-agents-docs-of-record技能说明
name: ai-agents-docs-of-record
version: 1.0.0
license: MIT
description: Runbook for this repo's documents of record. Session logs, ADRs, retrospectives, Serena memories, per-issue handoffs, plus the templates, validators, naming rules, and house prose style that bind them. Use when you say write the session log, create an ADR, fill the retro, save this to memory, which document of record. Do NOT use for authoring skills (use SkillForge) or research write-ups (use ai-agents-research-methodology).
metadata:
routing:
role: conditional-adjunct
invoker: ai-agents-research-methodology
trigger: ai-agents-research-methodology routes write-ups through the documents of record
user-facing: false
ai-agents-docs-of-record
This repo runs on verification-based governance. Continuity lives in per-issue
handoffs and Serena memory. Session log creation is discontinued; transcript
and pull request evidence remain valid, and the ~1,500 historical logs under
.project-toolkit/sessions/ stay in the repo as history.
Triggers
write the session logcreate an ADRfill the retrosave this to memorywhich document of record does this go in
The Record System Map
| Record | Location | Create with | Validated by |
|---|---|---|---|
| Session log (historical only, creation discontinued) | .project-toolkit/sessions/YYYY-MM-DD-session-NN[-slug].json | do not create new ones | scripts/validate_session_json.py, validate-if-present via the session-policy pre-commit hook, applies only if one is somehow staged |
| Per-issue handoff | .project-toolkit/sessions/handoffs/{YYYY-MM-DD}-{ISSUE}-handoff.md | copy .agents/templates/HANDOFF.md | resume-verification checklist at next session start |
| ADR | .project-toolkit/architecture/ADR-NNN-slug.md | adr-generator skill | scripts/validation/check_adr_uniqueness.py; adr-review debate gate |
| Retrospective | .project-toolkit/retrospective/ | retrospective skill on one of the four triggers (HIGH-tier reflect finding, main red, reverted or force-fixed merge, explicit user correction), or /retro fill on a historical skeleton | INDEX.md row (auto-appended, incomplete; see Phase 4) |
| Serena memory | .serena/memories/[domain]-[name].md | memory skill write conventions | curating-memories skill; memory-index routing |
Process
Phase 1: Pick the right record
| Situation | Record | Why |
|---|---|---|
| Issue spans multiple sessions | Per-issue handoff | Cold-start continuity (Issue #1725: 95.8% protocol failure without file-based gates) |
| Architectural or irreversible decision | ADR | Fires adr-review multi-agent debate |
| Incident, failure, or "what went wrong" | Retrospective | Feeds the failure canon; see ai-agents-failure-archaeology |
| Reusable pattern, correction, gotcha | Serena memory | Only memories are read by future sessions at start |
| User corrected you mid-session | reflect skill, then memory | Corrections not persisted are lost |
| A doc you touched is stale | Fix on contact (Phase 7) | Broken-windows rule |
One fact can need two records: an incident gets a retrospective AND a memory distilling the rule. The retro is the evidence; the memory is the searchable lesson.
Phase 2: Session logs (historical only)
Session log creation is discontinued (.claude/rules/session-logs.md MUST 1):
do not create a new .project-toolkit/sessions/*.json file. The ~1,500 existing logs
stay in the repo as history, schema at
.agents/schemas/session-log.schema.json (top-level required: session,
protocolCompliance with sessionStart and sessionEnd subsections), and
remain readable by retrospective, memory extraction, and the PreCompact
hook.
If a historical log is staged anyway (for example, cherry-picked from an older branch), it still needs to pass:
uv run python3 scripts/validate_session_json.py .project-toolkit/sessions/<file>.json
Hard requirements enforced by scripts/validate_session_json.py:
- Required
sessionfields:number,date,branch,startingCommit,objective. - Branch must match
^(feat|fix|docs|chore|refactor|test|ci)/. startingCommitmust be a 7-40 char lowercase hex SHA.
Historical naming may carry a slug:
2026-06-30-session-2600-skill-tooling-hygiene-taste-lints-naming.json. Never
resolve a session-log merge conflict with git checkout --ours; the settled
rule from the session 1187 incident is take --theirs and rename your own log
to the next free number (see ai-agents-failure-archaeology).
Phase 3: ADRs
Numbering collides here; treat numbers as claims, not identity. History:
concurrent ADR PRs each picked the same "next" number (Issue #2253), and
ADR-058/062/063 each existed twice until the duplicates were renumbered to
069/070/071 (Issue #2228, per the docstring of
scripts/validation/check_adr_uniqueness.py). ADR-055 and ADR-024 share the
slug github-actions-runner-selection (055 supersedes 024). Rule: when citing
an ADR, verify the file content says what you claim, not just the number.
python3 scripts/validation/check_adr_uniqueness.py --print-next
Workflow:
- Search first:
memory-searchfor prior decisions, then read neighbors in.project-toolkit/architecture/(ADR-007 memory-first: retrieval precedes reasoning). - Generate with
adr-generatoragainst.project-toolkit/architecture/ADR-TEMPLATE.md. - Claim the number from
--print-nextat the last moment before commit. - Expect the gate: any
ADR-*.mdcreate or edit fires theadr-reviewmulti-agent debate (AGENTS.md, "ADR Review"). Governance-level changes additionally need human appr