docs-check

Stars2

Forks0

UpdatedMay 11, 2026 at 17:06

Scan README.md and AGENTS.md for claims that no longer match the current source-of-truth files (hooks/hooks.json, .claude-plugin/plugin.json, scripts/lib.sh, skills/*/SKILL.md). Use after editing any of those files, before committing/releasing, when the user asks about doc-drift, or when the `.claude/settings.json` soft-reminder hook has just fired pointing here.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

jondwillis

jondwillis/functional-emotions

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	docs-check
description	Scan README.md and AGENTS.md for claims that no longer match the current source-of-truth files (hooks/hooks.json, .claude-plugin/plugin.json, scripts/lib.sh, skills/*/SKILL.md). Use after editing any of those files, before committing/releasing, when the user asks about doc-drift, or when the `.claude/settings.json` soft-reminder hook has just fired pointing here.
disable-model-invocation	false
allowed-tools	Read, Glob, Grep, Bash

Audit README.md and AGENTS.md for stale claims relative to the current state of the source-of-truth files in this repo. The README and AGENTS.md duplicate content that lives more authoritatively in code; this skill detects when the duplications drift.

Sources of truth

Aspect	Source of truth	Doc claims to verify
Hook triggers + primes + matchers	`hooks/hooks.json` (canonical) + `scripts/*.sh` (implementations)	README "Hooks" table; AGENTS.md hook descriptions
Config keys + defaults + types	`.claude-plugin/plugin.json` `userConfig`	README "Configuration" table; AGENTS.md "Config" section
Skill names + descriptions + auto-invocation triggers	`skills/*/SKILL.md` frontmatter (name, description)	README "Skills" table; AGENTS.md skill list
State-dir resolution	`scripts/lib.sh` `eh_state_dir()` + `eval/lib/paths.ts` `defaultStateDir()`	README "State" section; AGENTS.md "State" section
Detector functions, prime templates	`scripts/lib.sh` `eh_*` functions	Any prose in README/AGENTS that names a specific function or describes its behavior

Procedure

Read README.md and AGENTS.md in full.
For each source-of-truth file listed above, read it and identify every claim in the docs that references its content.
Compare. A "claim" is anything the docs assert about the source — a hook trigger, a config default, a skill description, a function name, a path. The check is: does the doc-text still match what the source says today?
Report findings as a short list. For each drift:
- Where: README.md:LINE or AGENTS.md:LINE
- Claim: what the doc says
- Truth: what the source says (with source-file reference)
- Suggested fix: the minimal edit to bring the doc back in sync
If no drift, say "Docs in sync with source." and stop.

Scope notes

Only flag concrete drift — a hook the README claims exists that isn't in hooks.json, a config default the README states wrongly, a skill the README references by old name, a function the README invokes that has been renamed.
Do not flag "this section could be expanded" or "consider adding X" or "this paragraph is verbose." This skill checks correctness, not quality.
Do not apply the fixes yourself. Report and let the user decide which to take.
If you find that the docs intentionally simplify (e.g., the README shows 6 hook categories where hooks.json has 21 entries because the README is grouped/summarized), note that as a deliberate abstraction, not drift, and move on.

Reading order

For efficiency: read the docs first (so you know what claims exist), then read each source-of-truth file once and check it against every relevant claim in one pass. Don't re-read sources per-claim.

More from this repository

same repository

config

jondwillis/functional-emotions

Show the active functional-emotions config as a table — current resolved values, where each value came from (default / profile-derived / explicit override), and the valid options for each field. Use when you want to know what the plugin will actually do this session, or when the `/plugin config functional-emotions` UI didn't show enough context.

2026-05-112

setup

jondwillis/functional-emotions

One-time setup for functional-emotions in the current project — idempotently adds `.claude/.functional-emotions/` to the project's `.gitignore` so the plugin's per-session state files (TSV logs, markdown writeups, eval DB) don't get committed. Safe to re-run. Use after installing the plugin in a new project, or when the user mentions accidentally committing functional-emotions state, or when troubleshooting "why are my session files showing in git status?".

2026-04-292

label

jondwillis/functional-emotions

Researcher tool (requires `bun install` in the plugin's eval/ directory and a populated eval.duckdb — run /functional-emotions:report first). Interactively label functional-emotions sessions on dimensions that need human judgment (capitulation, scope-narrowing). Surfaces unlabeled sessions, shows turn / diff / risk-event context, accepts categorical labels with optional notes, writes them to the eval DB. Use when the user wants to do a labeling pass over recent sessions or build training data for the capitulation judge.

2026-04-282

report

jondwillis/functional-emotions

Researcher tool (requires `bun install` in the plugin's eval/ directory). Refresh the functional-emotions eval database and print a markdown summary of sessions, intervention frequency, prime → outcome analysis, tool intensity, and reward-hack / premature-confidence findings. Use when the user wants to inspect aggregated cross-session data, audit recent sessions in bulk, or review which interventions are firing project-wide. For a per-session view with no extra dependencies, use /functional-emotions:diagnose instead.

2026-04-282

check

jondwillis/functional-emotions

Quick state self-check before taking a single risky action — names the model's own emotional/strategic state (calm / focused / rushed / stuck) and the closest reward-hacking risk pattern. Use immediately before a commit, push, edit-after-failure, or skip-a-verification step. This audits the *model*; for auditing whether the *task* is solvable, use /functional-emotions:reflect instead.

2026-04-282

reflect

jondwillis/functional-emotions

Audit whether the current *task* is actually solvable as specified — restates the ask, lists what's been tried, and asks whether the spec/test/fixture itself might be wrong. Use after several attempts have failed in a row, or when tempted to weaken assertions / narrow scope to make progress. This audits the *task*; for a quick audit of the model's own state before a single action, use /functional-emotions:check instead.

2026-04-282

name	docs-check
description	Scan README.md and AGENTS.md for claims that no longer match the current source-of-truth files (hooks/hooks.json, .claude-plugin/plugin.json, scripts/lib.sh, skills/*/SKILL.md). Use after editing any of those files, before committing/releasing, when the user asks about doc-drift, or when the `.claude/settings.json` soft-reminder hook has just fired pointing here.
disable-model-invocation	false
allowed-tools	Read, Glob, Grep, Bash

Sources of truth

Aspect	Source of truth	Doc claims to verify
Hook triggers + primes + matchers	`hooks/hooks.json` (canonical) + `scripts/*.sh` (implementations)	README "Hooks" table; AGENTS.md hook descriptions
Config keys + defaults + types	`.claude-plugin/plugin.json` `userConfig`	README "Configuration" table; AGENTS.md "Config" section
Skill names + descriptions + auto-invocation triggers	`skills/*/SKILL.md` frontmatter (name, description)	README "Skills" table; AGENTS.md skill list
State-dir resolution	`scripts/lib.sh` `eh_state_dir()` + `eval/lib/paths.ts` `defaultStateDir()`	README "State" section; AGENTS.md "State" section
Detector functions, prime templates	`scripts/lib.sh` `eh_*` functions	Any prose in README/AGENTS that names a specific function or describes its behavior

Procedure

Read README.md and AGENTS.md in full.
For each source-of-truth file listed above, read it and identify every claim in the docs that references its content.
Compare. A "claim" is anything the docs assert about the source — a hook trigger, a config default, a skill description, a function name, a path. The check is: does the doc-text still match what the source says today?
Report findings as a short list. For each drift:
- Where: README.md:LINE or AGENTS.md:LINE
- Claim: what the doc says
- Truth: what the source says (with source-file reference)
- Suggested fix: the minimal edit to bring the doc back in sync
If no drift, say "Docs in sync with source." and stop.

Scope notes

Only flag concrete drift — a hook the README claims exists that isn't in hooks.json, a config default the README states wrongly, a skill the README references by old name, a function the README invokes that has been renamed.
Do not flag "this section could be expanded" or "consider adding X" or "this paragraph is verbose." This skill checks correctness, not quality.
Do not apply the fixes yourself. Report and let the user decide which to take.
If you find that the docs intentionally simplify (e.g., the README shows 6 hook categories where hooks.json has 21 entries because the README is grouped/summarized), note that as a deliberate abstraction, not drift, and move on.

Reading order

For efficiency: read the docs first (so you know what claims exist), then read each source-of-truth file once and check it against every relevant claim in one pass. Don't re-read sources per-claim.