From caf7fa70c99a29e5a80a2b1e30d900800362a1dc Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 12 Aug 2026 09:26:03 -0700 Subject: [PATCH] docs: apply codex doc-review fixes for v1.62.0.0 - CLAUDE.md: scope the tier-alignment invariant claim (mapped files enforced, unmapped files reported) - docs/skills.md: document the plan-mode auto-select scope gate for /plan-eng-review and /plan-design-review - evals.yml: fix stale comment (PTY smokes register four skills, not two) Co-Authored-By: Claude Fable 5 --- .github/workflows/evals.yml | 17 +++++++++-------- CLAUDE.md | 6 ++++-- docs/skills.md | 4 +++- 3 files changed, 16 insertions(+), 11 deletions(-) diff --git a/.github/workflows/evals.yml b/.github/workflows/evals.yml index 4d2affa5a..3bb61f84b 100644 --- a/.github/workflows/evals.yml +++ b/.github/workflows/evals.yml @@ -169,14 +169,15 @@ jobs: console.log("seeded", p); ' - # PTY smokes drive the interactive `claude` TUI and send /office-hours and - # /plan-ceo-review. Claude Code discovers user-scoped skills from - # $HOME/.claude/skills//SKILL.md, but .claude/skills is gitignored, so - # a fresh CI checkout has NO registry — claude prints "Unknown command: - # /plan-ceo-review". Mirror setup's --no-prefix registry minimally: a gstack - # root symlink (resolves the preamble's absolute ~/.claude/skills/gstack/bin/* - # and ~/.claude/skills/gstack//sections/* paths) plus a per-skill - # top-level dir holding SKILL.md (+ sections) symlinks for the two skills + # PTY smokes drive the interactive `claude` TUI and send /office-hours, + # /plan-ceo-review, /plan-eng-review, and /plan-design-review. Claude Code + # discovers user-scoped skills from $HOME/.claude/skills//SKILL.md, + # but .claude/skills is gitignored, so a fresh CI checkout has NO registry + # — claude prints "Unknown command: /plan-ceo-review". Mirror setup's + # --no-prefix registry minimally: a gstack root symlink (resolves the + # preamble's absolute ~/.claude/skills/gstack/bin/* and + # ~/.claude/skills/gstack//sections/* paths) plus a per-skill + # top-level dir holding SKILL.md (+ sections) symlinks for the four skills # these tests invoke. No ./setup (it builds binaries, launches Chromium, # installs fonts, reads a /dev/tty prompt) and no binary build (SKILL.md + # bin/ + sections/ are committed). $HOME is /github/home here; the spawned diff --git a/CLAUDE.md b/CLAUDE.md index 89e8a1732..49515f480 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -71,8 +71,10 @@ periodic tests run weekly via cron or manually. Use `EVALS_TIER=gate` or 3. Requires external service (Codex, Gemini)? -> `periodic` Tier declarations are enforced by `test/e2e-tier-alignment.test.ts` (free, runs -in `bun test`): a `skill-e2e-*` file whose `EVALS_TIER` self-gate disagrees with -its declared tier in `E2E_TIERS` fails the suite — keep both in sync. +in `bun test`): a `skill-e2e-*` file named in a touchfiles dep list whose +`EVALS_TIER` self-gate disagrees with its declared tier in `E2E_TIERS` fails the +suite. Files not named in any dep list are reported, not enforced — keep both +in sync. ## Testing diff --git a/docs/skills.md b/docs/skills.md index 8e8cb7adc..ff524cf21 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -229,6 +229,8 @@ That is `/plan-eng-review`. Not "make the idea smaller." **Make the idea buildable.** +One note on invocation: in plan mode, the skill skips the "what should I review?" scope question and reviews your active plan automatically, announcing its pick in one line ("Scope gate: plan mode — auto-selected B") so you can redirect it. Name a target explicitly ("review PLAN.md") and your choice wins in any mode. Outside plan mode with nothing named, it asks first — that gate is a hard stop. + ### Review Readiness Dashboard Every review (CEO, Eng, Design) logs its result. At the end of each review, you see a dashboard: @@ -263,7 +265,7 @@ Most plans describe what the backend does but never specify what the user actual `/plan-design-review` catches all of this during planning, when it's cheap to fix. -It works like `/plan-ceo-review` and `/plan-eng-review` — interactive, one issue at a time, with the **STOP + AskUserQuestion** pattern. It rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. The rating drives the work: rate low = lots of fixes, rate high = quick pass. +It works like `/plan-ceo-review` and `/plan-eng-review` — interactive, one issue at a time, with the **STOP + AskUserQuestion** pattern. It rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. The rating drives the work: rate low = lots of fixes, rate high = quick pass. Like `/plan-eng-review`, it skips the "what should I review?" scope question in plan mode and targets your active plan automatically (announced in one line so you can redirect); an explicitly named target wins in any mode. Seven passes over the plan: information architecture, interaction state coverage, user journey, AI slop risk, design system alignment, responsive/accessibility, and unresolved design decisions. For each pass, it finds gaps and either fixes them directly (obvious ones) or asks you to make a design choice (genuine tradeoffs).