Remind

Remind — Lightweight Model Correction

Detect what rules or steps the model forgot, auto-load the relevant rule files, and execute the correction immediately. Think of this as a "conscience check" that reads the actual rules rather than relying on memory.

⚠️ CRITICAL: Execute, Don't Report

/remind is an executor, not a reporter. After detecting a violation:

1. Output the findings table (for traceability)
2. Invoke the correction command via Skill tool in the same reply — e.g., Skill: /codex-review-doc
3. Do NOT stop after outputting findings

There are exactly three exceptions, and § Step 4 defines them. They are not enumerated here: this file already learned that a second copy of the lifecycle diverges from the first within a round, so the copies were removed rather than kept in sync. What belongs here is the part § Step 4 does not carry — every executable owed correction is invoked, and "owed" is plural: two findings means two invocations.

Trigger

• Keywords: remind, forgot, check rules, what did I miss, you forgot to, re-read rules, drift, correction
• User suspects model skipped a required step or ignored a rule
• User explicitly says "你忘了做什麼" or similar

When NOT to Use

Modes

Smart Detection Mode

When invoked without arguments, run detection heuristics then dynamically load the relevant rules for each finding.

Step 1: Read State + Git

# Every git read in this step goes through one fence: the WHOLE `GIT_*` namespace
# unset in a subshell (the fence `scripts/lib/tree-digest.js` uses), and `-C "$PWD"`
# pinning the tree answered about. A named-variable list leaves
# `GIT_CEILING_DIRECTORIES`, `GIT_CONFIG*` and friends able to redirect or blind
# the read — and a blinded read looks exactly like a clean repository.
#
# Enumeration goes through `env`, NOT through `${!GIT_*}`. That expansion is a bash
# extension: zsh answers `bad substitution` and the whole fence returns nothing, so
# every read below fails at once — `TREE` captures the error text through its `2>&1`
# and a provably clean tree reports dirty, `BRANCH` empties and detection 4 can never
# fire. Measured under zsh 5.9, the shell the session pastes this block into. `env`
# costs a fork and is read the same way by bash, zsh and sh. `sed` anchors at `^GIT_`,
# so a value carrying an embedded newline can only ever synthesize another GIT_* name
# — never `PATH` — and unsetting a surplus GIT_* name is on the safe side of a fence
# whose whole purpose is unsetting them.
#
# The loop is not decoration, and neither is its shape. `unset $vars` would be wrong
# twice over: zsh does not word-split an unquoted `$var`, so several names would arrive
# as one, and on a GIT_*-free environment `unset` would be called with no operands at
# all — which bash accepts silently and zsh rejects with `unset: not enough arguments`,
# straight into `TREE` through its `2>&1`. Iterating a command substitution (which both
# shells DO split) runs zero times on the empty case and passes one quoted name at a
# time otherwise.
_remind_git() ( for v in $(env | sed -n 's/^\(GIT_[A-Za-z0-9_]*\)=.*/\1/p'); do unset "$v"; done; git -C "$PWD" "$@" )

# Anchor every path at the repository root. /remind is invoked from wherever the
# session happens to be, and a cwd-relative checker path turns an answerable run
# in `packages/app/` into a degraded one that reports both planes owed — over a
# root whose checker would have answered.
ROOT=$(_remind_git rev-parse --show-toplevel 2>/dev/null) || ROOT=""
[ -n "$ROOT" ] || ROOT="$PWD"

# The tree is asked ONE question, ONCE, and every answer below reads this result:
# is anything in it uncommitted. Two probes can disagree — a concurrent editor, a
# build writing into the tree, a wrapper answering differently the second time — and
# a step that classifies from one probe while reporting `DIRTY` from another accepts
# stale verdicts over a tree that moved between the two reads (reproduced with a git
# shim, round 17). stderr is folded in and a failed probe is not an empty one: a
# warning (an omitted directory, an unreadable submodule) or a nonzero exit means the
# tree is unverifiable, and unverifiable is owed. `--ignore-submodules=none` because
# a submodule carrying `submodule.<name>.ignore=all` otherwise suppresses its own
# superproject record, and empty-with-exit-0 is exactly the answer read as clean
# (`scripts/lib/tree-digest.js` handles the same case for the same reason).
if TREE=$(_remind_git status --porcelain=v1 -uall --ignore-submodules=none 2>&1) && [ -z "$TREE" ]; then
  TREE_CLEAN=true; DIRTY=""
else
  TREE_CLEAN=false; DIRTY="${TREE:-unverifiable}"
fi
unset TREE

# The reminder-state checker (hook-lightweighting §3.2): one computation of
# {noted, dirty, digest_match, verdict, rounds, passed, owed} per gate plane,
# derived from the live tree digest — `passed` already binds the recorded
# verdict to the current content, so no separate provenance check is needed.
# Installed copy first — the installer puts scripts under `.claude/scripts/`.
CHECKER="$ROOT/.claude/scripts/review-state.js"; [ -f "$CHECKER" ] || CHECKER="$ROOT/scripts/review-state.js"
ADV=""
if [ -f "$CHECKER" ] && command -v node >/dev/null 2>&1; then
  # Bounded *when a bounding tool exists*: the digest hashes dirty and untracked
  # content, which is unbounded on a pathological tree, and /remind runs
  # interactively. A kill lands in the fallback below. With none of
  # timeout/gtimeout/perl present the last branch runs node unbounded — the
  # ladder has no pure-shell rung. The `git status` probe above is unbounded for
  # the same reason.
  T="${AUTO_LOOP_DERIVE_TIMEOUT:-10}"; case "$T" in '' | *[!0-9]*) T=10 ;; esac
  [ "$T" -gt 0 ] 2>/dev/null || T=10
  if command -v timeout >/dev/null 2>&1; then
    ADV=$(cd "$ROOT" && timeout "$T" node "$CHECKER" check --format=json 2>/dev/null) || ADV=""
  elif command -v gtimeout >/dev/null 2>&1; then
    ADV=$(cd "$ROOT" && gtimeout "$T" node "$CHECKER" check --format=json 2>/dev/null) || ADV=""
  elif command -v perl >/dev/null 2>&1; then
    ADV=$(cd "$ROOT" && perl -e 'alarm shift; exec @ARGV or exit 127' "$T" node "$CHECKER" check --format=json 2>/dev/null) || ADV=""
  else
    ADV=$(cd "$ROOT" && node "$CHECKER" check --format=json 2>/dev/null) || ADV=""
  fi
fi

ADV_OK=false
if [ -n "$ADV" ]; then
  # `|| true`: a nonempty but malformed answer makes jq exit nonzero, and a failed
  # command substitution in an assignment aborts a caller that set -e — before the
  # fallback below could run. An empty value is the rejection this step wants anyway.
  _remind_bool() { echo "$ADV" | jq -r --arg p "$1" --arg k "$2" '.[$p][$k] | if type == "boolean" then tostring else "" end' 2>/dev/null || true; }
  HAS_CODE=$(_remind_bool code_review dirty); HAS_DOC=$(_remind_bool doc_review dirty)
  CODE_REVIEW=$(_remind_bool code_review passed); DOC_REVIEW=$(_remind_bool doc_review passed)
  PRECOMMIT=$(_remind_bool precommit passed)
  CODE_NOTED=$(_remind_bool code_review noted); DOC_NOTED=$(_remind_bool doc_review noted)
  # All seven or none — a partially parsed answer must not mix two policies. A
  # checker run outside a repository, or against a malformed state slot, either
  # exits nonzero (ADV empty) or yields non-boolean fields rejected here.
  if [ -n "$HAS_CODE" ] && [ -n "$HAS_DOC" ] && [ -n "$CODE_REVIEW" ] && [ -n "$DOC_REVIEW" ] && [ -n "$PRECOMMIT" ] && [ -n "$CODE_NOTED" ] && [ -n "$DOC_NOTED" ]; then
    ADV_OK=true
  fi
fi

if [ "$ADV_OK" != "true" ]; then
  # Checker unavailable, so the ONE tree answer taken above is all there is, and it
  # opens both planes or neither. It deliberately does NOT classify: only the
  # checker does that, by full-path suffix over the whole repository.
  # Per-plane pathspec probes were tried and removed, because an ordinary pathspec is
  # relative to the CWD: run from `sub/`, `-- '*.md'` cannot see a dirty `guide.md` at
  # the root while a negative-only probe still reports it, so a doc-only change reads
  # as code-only (measured, git 2.51). Fixing that needs `:(top,glob)` magic on every
  # pattern, and even then the stderr rule stays per-probe. A degraded path that
  # guesses wrong hides a gate; one that over-reminds costs a redundant review
  # dispatch, since this skill executes its corrections rather than printing them —
  # real tokens, but never a hidden obligation.
  if [ "$TREE_CLEAN" = "true" ]; then
    HAS_CODE=false; HAS_DOC=false
  else
    HAS_CODE=true; HAS_DOC=true
  fi
  # No verdict without the checker — not even on a clean tree. The state slot lives
  # outside the repo keyed by a non-contractual hash, so this step cannot read it
  # directly, and `git status` cannot supply the digest binding: "clean" says
  # nothing is uncommitted *now*, which is equally true one checkout later, so a
  # PASS earned on commit A would read as current on an unrelated, equally clean
  # commit B. The degraded run answers the change question from git and leaves
  # every verdict `false`, and the noted flags with them.
  #
  # What that costs, stated plainly: detections 3 and 5 cannot fire on a degraded
  # run — 3 triggers on a verdict and 5 on a noted flag, and this path has neither.
  # Detections 1 and 2 still work off the tree. The trade is deliberate — a missed
  # nudge, rather than a stale PASS closing the current gate.
  CODE_REVIEW=false; DOC_REVIEW=false; PRECOMMIT=false
  CODE_NOTED=false; DOC_NOTED=false
fi

# Branch — same fence, so a redirected environment cannot report a feature branch as
# `main`. A different question from the tree probe above, hence a separate read;
# `DIRTY` is NOT re-read here, because a second tree answer is what round 17 killed.
# The `|| VAR=""` is not decoration: under a caller's `set -e` a failed command
# substitution in an assignment aborts the shell, and this step would then exit
# before its own cleanup line.
BRANCH=$(_remind_git rev-parse --abbrev-ref HEAD 2>/dev/null) || BRANCH=""

unset -f _remind_git _remind_bool 2>/dev/null || true

Step 2: Detection → Rule Mapping

For each detected issue, Read the mapped rule file and extract the key section:

Without the checker (ADV_OK=false) the step does not classify, so HAS_CODE and HAS_DOC move together, and no verdict and no noted flag are available at all — the state slot is never read directly on any degraded run, however clean the tree looks (see Step 1's comment: clean means "nothing uncommitted now", which an unrelated commit satisfies just as well). What remains:

So on a degraded dirty tree rows 1 and 2 are never separable — one shared cause, stated once ("checker unavailable, so both planes are reported as changed and no verdict is trusted"), not two independent detections. Never disclose source=state on a degraded run, and never dispatch /precommit from row 3 there: no state was read, and row 3 cannot have fired.

Step 3: Output with Rule Context

For each finding, quote the relevant rule text inline so the model re-ingests the rule:

## Reminder

### Findings

| # | Priority | Rule | Issue | Correction |
|---|----------|------|-------|------------|
| 1 | P0 | auto-loop | Code changed but review not passed | `/codex-review-fast` |

### Rule Context (auto-loaded)

> **auto-loop.md — Terminal completion invariant**: work on a change may be declared complete
> only when every gate its change class requires has passed after the last edit in that
> gate's change class.
> - ❌ Declaring ≠ Executing: naming a gate is not running it
> - ❌ Summary ≠ Completion: a report does not close an open gate
>
> **Required action**: Execute `/codex-review-fast` in this reply, do not stop.

### Corrections (copy-pasteable)
1. `/codex-review-fast`

Step 4: Execute the correction — in the same reply

The output above is the traceability record, not the deliverable. Immediately after printing it, invoke the correction through the Skill tool (Skill: /codex-review-fast) and report what it returned. A findings table followed by a stop is the exact failure this skill exists to correct — see § Execution Contract, which this step is the operational half of.

Every owed correction, not the first one. Two rows can fire at once — a degraded dirty tree owes both /codex-review-fast and /codex-review-doc — and stopping after one leaves the other plane open, which is the same defect in a smaller shape. Run them one at a time and re-read Step 1 after each: a review that edits files moves the tree, so the remaining plan computed before it may no longer be the right one.

Detection 4 is advisory and has no correction Skill. Being on main is corrected by creating a branch, and @rules/git-workflow.md does not authorize this skill to run git checkout/switch — nor is there a branch name to choose. State the finding and the command the human can run; that is the whole of it. If detection 4 is the only finding, this step ends without an invocation.

A degraded run terminates too, and not by claiming All Clear. Without the checker there is no verdict, so re-reading Step 1 after a correction returns the same rows it returned before — /codex-review-fast cannot make CODE_REVIEW true when nothing can read a verdict. Degradation dominates the terminal status: whenever ADV_OK is false the reply ends at ### Degraded ⚠️, whether or not detection 4 also fired and whether or not a correction ran. Two rules keep that from becoming a loop or a false clearance:

So the complete list of outcomes that end this step without an invocation is three: ### All Clear ✅ (the checker answered and nothing is owed), a lone detection 4 on a run the checker answered, and ### Degraded ⚠️ where no executable correction fired. A degraded run that did invoke corrections ends at ### Degraded ⚠️ too — that one is a termination, not an exception.

Specific Rule Mode (/remind <rule>)

When user provides a rule name:

1. Resolve: rules/<rule>.md → if not found, try rules/<rule>-project.md → if not found, list available via Glob("rules/*.md")
2. Read: Read the full rule file
3. Summarize: Extract core principles, prohibited behaviors, required actions
4. Check: run Step 1 and use the variables it resolved. Not the state slot directly — the checker's passed is what binds the stored verdict to the current tree digest; a raw slot read after a subsequent edit reports compliance over an owed review. Where the checker cannot answer, Step 1 says so
5. Output: rule summary + current violation status + correction commands, then Step 4 — the execution contract applies to this mode too

Nuclear Mode (/remind --all)

When the model keeps drifting despite specific reminders:

1. Read CLAUDE.md: Extract ## Required Checks table + ## Auto-Loop section
2. Read all rules: Glob("rules/*.md") → Read each file
3. For each rule: Extract prohibited behaviors / core principles
4. Cross-reference: Step 1's resolved variables against all rules — same reason as above, the state slot is not a second source of truth
5. Output: full compliance report with every rule's status, then Step 4

This is the "nuclear option" — high token cost but guarantees the model re-ingests all project rules. Use when repeated /remind calls haven't fixed the drift.

Arguments

Graceful Degradation

Execution Contract (reinforces top-level CRITICAL section)

The reminder output isn't just informational — it's a correction directive with mandatory execution:

1. Invoke the correction Skill for every executable owed finding, immediately in the same reply — do not ask for permission, do not output a summary and stop. Two findings means two invocations, Step 1 re-read between them. Which runs end without an invocation, and how a degraded run terminates, are § Step 4's to state — there are three exceptions and this list is not a fourth copy of them
2. Re-read the quoted rule text — it was loaded from the actual rule file specifically because the model drifted from it
3. Do not dismiss findings with "I already did that" unless you can point to the specific tool invocation in this conversation
4. If findings say "run /codex-review-fast" — invoke Skill: /codex-review-fast now, not later

The whole point of /remind is that the model's memory of rules has drifted. The quoted rule text is the source of truth, not the model's recollection of what the rules say.

Correct flow:

/remind → detect doc-no-review → output findings table → invoke Skill(/codex-review-doc) → report result
/remind → detect code-no-review → output findings table → invoke Skill(/codex-review-fast) → report result
/remind → nothing to invoke → the outcome that terminates the run is § Step 4's to name

Examples

Input: /remind
Output: Smart detection finds code changed without review → loads auto-loop.md → quotes the terminal completion invariant → prints the findings table → **invokes `Skill: /codex-review-fast`** and reports its verdict

Input: /remind auto-loop
Output: Reads rules/auto-loop.md → summarizes the terminal completion invariant + gate sequence → checks Step 1's resolved state → reports compliance → **invokes the correction Skill** if anything is owed

Input: /remind --all
Output: Reads CLAUDE.md + all rules/*.md → produces full compliance matrix → **invokes every owed correction Skill in turn**, re-reading Step 1 between them

Input: /remind git-workflow
Output: Reads rules/git-workflow.md → summarizes branch naming + forbidden operations → checks current branch → warns if on main and prints the `git checkout -b` the human can run (detection 4 is the advisory exception in Step 4 — this skill does not create branches)

Verification Checklist

• Detection heuristics ran (Step 1's checker, or its disclosed git fallback)
• Relevant rules dynamically loaded (Read tool)
• Rule text quoted inline for model re-ingestion
• Correction commands are copy-pasteable
• Every owed correction Skill invoked in this reply, Step 1 re-read between them — the three exceptions and the degraded run's termination are defined in § Step 4 and are not restated here, because a checklist that re-enumerates a contract is a second copy to drift from
• No git add / git commit / git push executed

References

• references/detection-rules.md — Detection → rule mapping table + extraction patterns