| name | session-critique |
| auto-activate | false |
| description | Use when you explicitly want adversarial, decision-aware critique of a session's completed work before committing — invoke it manually with /session-critique. Reviews every changed artifact (code, data, report) as a senior software engineer and AI researcher, asking: did the work follow the decisions you made this session, follow repo rules, stay un-over-engineered, and leave the codebase maintainable and extensible? Stops at each HIGH/MEDIUM finding to discuss the fix with you before applying it, batches LOW nits, and applies only the fixes you authorize. NOT for single-file trivial edits (use /validate directly) or standard code review without fixes (use /multi-review).
|
Session Critique: Decision-Aware Adversarial Review
Spawn an advisor-pattern agent team that reviews all work done this session — code, data,
and report artifacts — acting as a senior software engineer and AI researcher. The bar is
not only "is it correct and finished?" but two forward-looking questions:
- Decision adherence — did the implementation follow the decisions the user made during
this session?
- Build-on-top, not patch-on-patch — did the work leave a codebase the next task can
extend, or a hodgepodge the next task must spend its time untangling? Elegant solutions,
not a regression backlog.
Surface every finding for user approval; apply only the fixes the user authorizes.
Be honest and transparent. Surface uncertainty explicitly. Never rationalize an incomplete
or "good enough" result as done — name what is unfinished and why.
When to use
- Session produced multi-file changes (code / data / report) that should be stress-tested
- You want adversarial self-critique + code quality review before committing
- You want to confirm the implementation honored the decisions you made this session
- You need independent verification that nothing was missed, mis-stated, or over-built
When NOT to use
- Single-file trivial edit — run
/validate directly
- Standard code review without fix authority — use
/multi-review
- Only need diff/security/schema checks — use
/validate
- Work is not yet complete — finish implementation first
Decision Authority
The user approves ALL non-trivial decisions. No teammate decides autonomously.
Teammates CAN without asking: read files, run verification commands, spawn subagents, report
findings.
Teammates MUST escalate (via lead -> user): applying any fix, dismissing any finding, resolving
disagreements, any file content change.
Procedure
Phase 0: Scope + Session Decisions Ledger
Scope the changed artifacts:
git log --oneline -10
git diff HEAD --name-only
git status --porcelain
git diff <first-session-commit>~1..HEAD --name-only
Split files into ownership buckets (no overlap), by artifact type:
- Bucket A (self-critic): modifications to existing code + docs
- Bucket B (code-reviewer): newly created files, CLAUDE.md / index files, and report/output
artifacts. For generated reports, defer domain-specific number/citation verification to the
appropriate specialized skill — do not reimplement it here.
- Data artifacts (
results/, generated data): review read-only. NEVER propose editing,
deleting, or overwriting an existing result file — the result-protection PreToolUse hook
blocks it. A wrong-looking data file is a finding against the generating code/spec, or a
flag for the user — never an edit under results/.
- If a split is unclear: ask the user.
Build the Session Decisions Ledger. The user's in-session decisions live in this
conversation, not in git — and the teammates you spawn will not have the conversation. So you
(the lead) extract them first. Write a numbered ledger of every explicit choice or direction
the user gave this session:
SESSION DECISIONS LEDGER
1. Chose X over Y because <reason>
2. Directed: use approach Z for <component>
3. Constraint: do NOT do W
...
Confirm the ledger with the user before spawning teammates: "Here are the N decisions I'll hold
the work against — anything missing or misremembered?" This ledger is the contract the team
measures implementation drift against.
Cross-session caveat: this reconstruction works because /session-critique runs at the
end of the same session. If invoked in a fresh session the conversation is gone — fall back
to commit messages + handoff docs for the ledger, and say so explicitly.
Phase 1: Team Design + User Approval
Present the team design table to the user. WAIT for approval before launching.
| Teammate | Model | Role | Owns |
|---------------|--------|-------------------------------------------------|------------|
| advisor | opus | Strategic direction + Elegance Gate, read-only | All (read) |
| self-critic | opus | Adversarial self-review | Bucket A |
| code-reviewer | sonnet | Code quality + structural + report | Bucket B |
The lead runs ONE plan-reviewer subagent in Drift Detection mode, fed the Session Decisions
Ledger, as the single decision-adherence check (workers do not each re-run it).
Cost: ~65-75% of all-Opus equivalent
Phase 2: Launch (advisor pattern)
TeamCreate(team_name="session-critique")- Create tasks with
TaskCreate for each work unit
- Spawn advisor (Opus) FIRST — use
advisor-prompt.md from /agent-team skill
- Wait for "ADVISOR READY"
- Spawn workers using the model assignments above (self-critic Opus, code-reviewer Sonnet)
with filled prompts from teammates.md — include the Session Decisions
Ledger verbatim in each worker's brief
- Every
Agent call MUST include team_name
Phase A: Analysis (parallel, no edits)
Both workers analyze simultaneously. Advisor reviews as findings arrive. No files are
modified. Each worker runs its audit checklist from teammates.md, plus the
forward-elegance audit (per changed unit: one clear purpose? a well-defined interface?
understandable and testable on its own? follows existing patterns or a one-off bolt-on? will
the next task build on this, or fight it?).
Decision-adherence is a single session-level pass — not a per-worker one. The lead spawns
one plan-reviewer subagent in Drift Detection mode with the Session Decisions Ledger; it
checks the whole implementation against each ledger item (Done-sentence mismatch, scope drift,
Must-NOT violation) and returns one authoritative adherence report. Workers do not each re-run
it — they only flag drift they happen to spot in passing.
Output: two worker findings reports + one drift report (all severity-tagged).
Workers consult advisor (Section 7 of teammate-prompt.md): brief approach before starting,
present options at decision points, escalate after 2 failed attempts, send findings to lead +
advisor when done.
Phase A.5: Elegance Gate (advisor — whole-session step-back)
After the per-file findings are in, the advisor runs ONE whole-session Elegance Gate. Think
carefully. Step back from the individual changes and look at what this session set out to
accomplish:
- Is the work solving the right problem, or has it drifted into solving a side-effect?
- Is there a fundamentally simpler or more coherent shape the whole body of work should have
taken — a different structure, an existing utility, a known pattern — that would make much of
it unnecessary?
- Would an experienced engineer look at the session and say "why not just do X instead?"
Output one of: "the overall shape is right because ," or a concrete counter-proposal
(what the alternative is, why it's better, its tradeoffs, what in the session's work it would
replace). This is not a formality — do not skip it.
Phase B: Decision Loop (user decides, one issue at a time)
The lead collects all findings + advisor recommendations + the Elegance Gate verdict, then
normalizes every finding to one canonical 4-tier scale (incoming findings use different
vocabularies) and sorts by severity:
| Canonical | Means | Sources map in | Loop treatment |
|---|
| BLOCK | Halt — must be fixed or explicitly waived before commit | self-critic BLOCK; plan-reviewer critical | serial, first |
| HIGH | Serious; discuss before deciding | plan-reviewer high; self-critic HIGH | serial |
| MEDIUM | Worth a decision | medium | serial |
| LOW | Nit / advisory | self-critic WARN; low | batched at end |
BLOCK, HIGH, and MEDIUM findings — serial, one at a time (BLOCK first). For each:
=== ISSUE k of N [BLOCK|HIGH|MEDIUM] ===
[file:line] <issue>
Why it matters: <consequence if unfixed — regression risk, decision drift, maintainability cost>
Decision-Ledger link: <which ledger decision this violates, or "none">
Advisor recommendation: <approach> because <reason>
Options: A) <fix> B) <alternative> C) leave as-is because <when that is right>
STOP. Discuss with the user. The user decides the approach. Apply the chosen fix, verify it
(state before/after), then move to the next issue. Do NOT batch BLOCK/HIGH/MEDIUM — each gets
its own discussion. A BLOCK left unresolved and unwaived halts the commit.
LOW / advisory findings — one batch at the end. After the High/Med loop completes, present
all LOW findings as a single numbered list for approve-all / cherry-pick:
=== LOW / ADVISORY (batch) ===
1. [file:line] <nit> -> <suggested fix>
2. ...
Type approvals (e.g., "1,3,5", "all", or "none").
Phase C: Fix Verification
Every applied fix — BLOCK/HIGH/MEDIUM (in-loop) or LOW (post-batch) — is verified before/after
by the owning worker. The advisor reviews all applied changes (Phase C quality gate) for
accuracy and scope compliance.
Phase D: Handback
Lead reviews any out-of-scope changes introduced by this critique. Do not revert
pre-existing local work or ambiguous changes without explicit user approval:
git diff --stat HEAD
git diff --name-only HEAD
If a file is out-of-scope and the critique introduced the change, ask the user
before reverting it. If a file was dirty before the critique began or ownership
is unclear, report it and leave it untouched.
Confirm no existing file under results/ was modified. Present the final summary:
ledger decisions checked (adhered / drifted), Elegance Gate verdict, fixes applied
(High/Med + Low), findings dismissed (with reasons). The user runs /validate
and commits at their own discretion.
Critique is Done when
- Every BLOCK/HIGH/MEDIUM finding has been discussed with the user and resolved (fixed or
dismissed with a recorded reason); no BLOCK remains unresolved or unwaived
- Every LOW finding has been presented in the batch and dispositioned
- Each Session Decisions Ledger item has been marked adhered or drifted
- The advisor's whole-session Elegance Gate has produced a verdict
- No existing
results/ file was modified; out-of-scope changes introduced by
the critique were resolved with user approval, and pre-existing local work was
left untouched
Report Format (each worker sends to lead after Phase A)
## [Role] Findings (AWAITING APPROVAL)
### Issues Found: N
| # | File | Issue | Severity | Decision-Ledger link | Proposed Fix | Alternatives |
|---|------|-------|----------|----------------------|--------------|--------------|
| 1 | ... | ... | high/med/low | #2 (drift) / none | [fix A] | [fix B], [skip] |
### Decision adherence (plan-reviewer drift pass): [adhered / drifted on #k, ...]
### Forward elegance: [units that the next task will build on / fight, with reasons]
### Advisor consultations: N
### Subagent results: [agent: PASS/FAIL (N issues)]
### Cross-team issues flagged: [list if any]
Common Mistakes
| Mistake | Prevention |
|---|
| Teammates fix files without user approval | Two-phase workflow: ANALYZE then FIX after approval |
| Batching BLOCK/HIGH/MEDIUM into one approval list | Phase B is serial for those — one issue, one discussion, one fix |
| Skipping the Session Decisions Ledger | Phase 0 builds + confirms it before any teammate spawns |
| Treating the Elegance Gate as a formality | Phase A.5 must produce a real verdict or counter-proposal |
Proposing edits to results/ data files | Data is read-only; fix the generating code/spec or flag for user |
| Teammates edit out-of-scope files | Explicit bucket ownership + Phase D review; revert only critique-introduced changes with user approval |
| Advisor makes final calls instead of user | Decision authority rule: advisor recommends, user decides |
| Lead commits without user running /validate | Phase D hands back — user owns validation and commit |
Red Flags — STOP and Escalate to User
- Worker editing a file before Phase B approval
- Worker dismissing a finding as "not worth fixing" without escalating
- Any proposed Edit/Write/rm targeting an existing file under
results/
- BLOCK/HIGH/MEDIUM findings presented as a batch instead of one at a time
- Advisor approving fixes on the user's behalf
- Any teammate contacting the user directly (all goes through lead)
- Out-of-scope files appearing in
git diff --stat HEAD
See teammates.md for detailed worker specifications, skills, subagents, and
audit checklists.
