retro
Trend review across many sessions - velocity vs planned dates, eval-score trend toward target, failure-category trends from journal triage and investigations, and a status check on every open PLAN risk. Reads JOURNAL/PLAN/eval history, writes a dated retro entry into JOURNAL.md. Use when the user asks for a retro, a weekly review, or a phase-end wrap-up.
- License 许可
- MIT
- 最近更新
- 2026-09-28
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- retro
- description
- Trend review across many sessions - velocity vs planned dates, eval-score trend toward target, failure-category trends from journal triage and investigations, and a status check on every open PLAN risk. Reads JOURNAL/PLAN/eval history, writes a dated retro entry into JOURNAL.md. Use when the user asks for a retro, a weekly review, or a phase-end wrap-up.
- argument-hint
- [week | phase N | notes]
02 资源文件 1
- 参考文档references/retro-sections.md2.8 KB
03 SKILL.md 正文
/retro — the trend across sessions
/journal records one session; /retro reads many and says where the line is heading. Not a summary — a trend, with the numbers that make "we're slipping" or "the eval is climbing" a fact instead of a feeling.
Adjacent skills: /journal (one session's worklog; /retro trends across
many) · /audit eval (one report's honesty; /retro the trend across runs)
· /triage (grooms the backlog; /retro reviews the trajectory).
<!-- acstack:runtime --> Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:
link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)" # empty = not symlinked
pack="$(dirname "$(dirname "$link")")" # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
"$pack/bin/acstack-config" || true # resolved keys, with sources
"$pack/bin/acstack-update-check" || true # ≤1 fetch/day; silent ONLY if already checked today
"$pack/bin/acstack-recall" || true # LEARNINGS.md + bug-class names, capped 3KB
else
echo "runtime off — proceeding without recall/update-check"
fi
<!-- /acstack:runtime -->
<!-- acstack:principles -->
Operating principles
- Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
- Never delete a decision. Supersede it:
~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason. - Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
- Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
- Attribution: follow the project's
attributionsetting (defaultnone) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit-m/-Fmessages only. - Config: read
.claude/acstack.mdat the project root (fall back to~/.claude/acstack.md) before acting.## Settingskeys override pack defaults; a## <skill-name>section overrides both. Unknown keys and sections are ignored. - Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
- Recall: if
LEARNINGS.mdexists at the project root, read it before starting. - Conduct: follow the
acstack-conductblock in this repo's AGENTS.md — the word is the mode; the user sets the pace. - Hackathon lane: if the project's AGENTS.md carries the
acstack:hackathon-laneblock, only/dochanges the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route. <!-- /acstack:principles -->
One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name
its path in the report's scope line. If more than one candidate set exists
— a monorepo, nested products, an apps/* tree each with its own docs —
list the candidates and STOP. Never pick one silently: a confident answer
about the wrong product is worse than no answer (conduct rule 8).
Inputs
- JOURNAL.md entries since the last retro (the window;
weekorphase Nin the argument narrows it). - PLAN.md: planned phase dates, exit criteria, the open risks and items.
- Eval artifacts when present:
eval/spec.mdtargets and the result files across runs. git logover the window for commit / checkbox velocity.
Retrieve by window, don't ingest the file. Past roughly 500 lines,
JOURNAL.md is read headings-first: scan the ### entry headings and their
dates, select the ones inside the window (week, phase N, or since the
last retro), and fetch full text for those only. Entries outside the window
are not evidence for this retro — reading them wastes budget and, worse,
invites a trend claim drawn from data the window explicitly excluded. State
the window and how many entries fell inside it, so a reader can tell a
five-entry trend from a one-entry anecdote.
Missing inputs are named, never worked around. No JOURNAL.md → stop:
a retro is a trend across recorded sessions, and without the record there
is no trend, only the git log's shape — say that and point at /journal.
No PLAN.md → run the trends that only need the journal and state that
velocity-vs-plan and the risk review were skipped for want of the plan. A
window containing one entry is reported as one entry, not extrapolated
into a trend.
Sections
The four sections live in references/retro-sections.md with their
question sets and honest-degradation lines. Lead with a verdict:
on plan / slipping — <where> / off plan.
- Velocity vs plan. Planned phase dates vs actual; boxes or issues closed per period vs the plan's implied rate; slippage named in days with the cause pulled from journal entries, not guessed.
- Eval trend. Headline score per run across the window, per-category direction, distance to target. No eval history → one honest line and the section ends.
- Failure-category trends. Counts by class from the journal's eval triage sections and /investigate write-ups; a class recurring 2+ times is named as a /learn promotion candidate.
- Risk review. Each open PLAN risk: still real / materialized / retired, with evidence. New risks are proposed as dated PLAN edits — proposed, never applied by /retro.
Not in wave 3
No skill-usage / telemetry section — it arrives with the local telemetry it reads (PLAN task 4.3, moved to wave 4.5 post-launch by the 2026-07-29 split). Don't emit a placeholder for it; its absence is correct, not a gap.
Output
Append to JOURNAL.md as a dated entry under ## Key decisions and journey, newest first:
### Retro (YYYY-MM-DD — <window>). This is the same anchor /journal
writes at, so a retro and a journal entry from two concurrent sessions
conflict — which is the safe outcome, and is resolved by keeping both
entries rather than choosing one (see /journal step 2). A journal without that heading —
hand-kept rather than seeded from /journal's template — takes the entry
per that journal's own convention: appended where its entries actually
go (top of a newest-first record, bottom of a chronological one), with
the divergence named inside the entry; never scaffold the pack's
skeleton into a journal the project keeps by hand, and never impose the
pack's ordering on it. Commit using the project's
journal-commit-format (pack default Journal <date>: <summary>) with
retro — <summary> as the summary, brief body, attribution per config.
PLAN edits the retro proposes are listed for the user to apply
via /plan replan — /retro writes the journal, not the plan.
Tickets-mode delta
Velocity becomes closed issues + milestone burn via
gh issue list --state closed and the milestone API; failure classes
are additionally mined from issue labels and closing comments.
Preconditions — gh installed, gh auth status succeeding, and a
GitHub remote present. Any failure names WHICH one failed and offers
document mode; never guess.
04 同仓库更多 Skills
why
Decision archaeology - answers why the code, config, or plan is the way it is by searching the record in a fixed order: BRIEF constraints, dated PLAN decisions, JOURNAL entries, then git history. Stops at the first real answer, cites it with a date, and says no recorded rationale rather than inventing one. Use when someone asks why something is this way, why a choice was made, or where a decision is written down.
verify
Audit a completion claim made by someone else - another session, agent, or teammate - against the running system rather than the diff. Re-derives what the claim's acceptance demands, runs it, and returns CONFIRMED, OVERSTATED, FALSE or UNVERIFIABLE with the command and its output. Never fixes, never edits the claim or the acceptance. Use when handed a "done", "all green", "merged" or "it works" you did not produce yourself.
triage
Backlog hygiene sweep - stale items, duplicate pairs, missing acceptance criteria, unblocked-but-unassigned work, and milestone burn, delivered as a report first with only user-approved actions applied. Works on GitHub Issues in tickets mode and on PLAN.md checkboxes in document mode. Use when the user asks to triage, groom, or clean up the backlog or the plan's open tasks.
ticket
Capture a brain-dump as a well-formed work item - verb-first title, acceptance criteria, file paths when known, an out-of-scope line. Files a GitHub issue in tickets mode or appends a numbered PLAN.md task in document mode; unknowns are marked TBD, never invented. Use when the user brain-dumps an idea, bug, or task to capture for later, or asks to ticket, file, or note something as work.
ship
Branch-level release with five gates before the act - clean-state, tests, eval-vs-target, docs drift, and attribution sweep; any failing gate stops the release with its output. Then push, and under push: branch-pr open a report-shaped PR wiring the issue-closing reference in tickets mode or PLAN task IDs in document mode. Use when the user asks to ship, release, cut, or open the PR for a feature or branch.
secure
Security review with a confidence gate - a finding exists only with a concrete exploit scenario and a high/medium/low confidence rating; everything else goes to a worth-hardening list, never inflated. Sweeps five surfaces: auth gates, secrets hygiene, injection and unsafe sinks, unsafe deserialization/crypto/transport, and LLM tool-use trust boundaries. Reports only, never fixes. Use when the user asks for a security review or to check vulnerabilities, secrets, or auth.