progressive-disclosure refactor of SKILL.md (302 → 159 lines) + scope-comma guard, v1.8.0

[FWcloud916]

What changed

Executes the writing-great-skills improvement plan for the progress-tracker skill, in eight reviewable commits (each passed the full gate before the next started):

1. Migration split — new references/migration.md is the single authoritative migration document (discovery/consent, KI-001 rationale, merged step-by-step flow, authoritative command reference, Kind/disposition rules). It absorbs both SKILL.md's ~110-line migration detail and workflow.md's parallel seven-step section. SKILL.md and workflow.md keep only the preflight rules, the byte-synced MIGRATION_GATE block, and an imperative read-in-full pointer.
2. Description rewrite — front-loads the preflight leading word, gives each lifecycle branch (create / update / audit / close out / migrate) exactly one trigger, drops identity prose duplicated by the body. 110 words, activation boundary unchanged → trigger matrix untouched. Invocation-semantics decision recorded in docs/design-decisions.md.
3. Leading words — "Migration is a two-phase commit: the audit is the prepare phase; nothing is deleted until it votes yes." anchored above the gate block and at migration.md's opening, deliberately outside the byte-synced markers. Negation scan: hard guardrails stay verbatim; soft negations rewritten positively.
4. Phase 4 — Shared Vocabulary section in docs/domain-models.md (instead of a new CONTEXT.md), a six-failure-mode SKILL.md editing checklist in AGENTS.md, an eval-tautology audit recorded in design decisions, and the plugin version bump 1.7.1 → 1.8.0 in both manifests.
5. README harmonization — README's fourth (most drift-prone) paraphrase of the audit conditions collapsed into the two-phase-commit framing with a link to the authoritative doc.
6. External corroboration — design-decision addendum mapping the refactor onto Anthropic's "new rules of context engineering for Claude 5 generation models" post, including the deliberate divergences.
7. Interface-design experiment (adopted) — SKILL.md's Key-arguments list and option prose replaced by a "read --help before first use" pointer, evaluated via a fact-by-fact coverage matrix against live --help output and probed error messages.
8. Scope-comma guard (CLI change) — the one silent-failure trap found in (7) is now loud: an unescaped --scope comma with adjacent whitespace is rejected as ambiguous (error teaches both resolutions), empty entries (trailing/leading/doubled comma) are rejected instead of silently dropped, and both CLIs echo the parsed scope names (Scope: api · worker (2 entries)) in normal mode. The escaping rule then moved out of SKILL.md into --help. Final SKILL.md size: 159 lines.

Why

Migration is a single-branch path, yet its detail occupied ~110 of SKILL.md's 302 lines of always-loaded context, and the same seven-step contract was restated nearly in full in workflow.md. This PR moves that cost behind a pointer, deduplicates the contract to one authoritative home, prunes no-op sentences, defers argument semantics to the CLI's own interface, and hardens the one input ambiguity that used to fail silently — SKILL.md lands at 159 lines (was 302).

Reviewer notes

• The MIGRATION_GATE block remains byte-identical in SKILL.md, workflow.md, and agents/progress-tracker.md (verify.sh check 3b) and is deliberately not copied into migration.md — that would be a fourth, unchecked drift copy.
• agents/progress-tracker.md keeps its condensed migration paraphrase (a subagent definition must be self-contained) plus the same read-in-full pointer; recorded as accepted residual duplication in design decisions.
• SKILL.md's status-meaning and transitions tables were compressed to prose keeping only behavior-bearing facts (review ≠ done, planning default, terminals); the frozen lifecycle diagram remains canonical and the script still enforces transitions.
• Argument-semantics deletion was gated on interface coverage: every removed sentence is taught by --help or by an actionable error at the moment of the mistake. Method recorded in docs/design-decisions.md.
• The scope-comma guard's blast radius was verified before design: no existing pytest case, scenario, or documented example uses whitespace-adjacent commas, so no previously-valid documented input changes meaning; api,worker (no whitespace) still separates entries.
• migration.md is intentionally absent from verify.sh's scaffold-link map, so it is never copied into user projects; scaffolded seed docs already direct readers back to the installed skill.
• Dogfooded: the effort was tracked with the skill's own scripts (progress/2026-07-28-skill-docs-progressive-disclosure/), including the enforced in-progress → review → done close-out.

Verification

• bash scripts/verify.sh — all 22 checks pass (includes pytest with 16 new cases, grader regression, and the 15 end-to-end scenarios)
• uvx ruff==0.16.0 check . — clean (CI-pinned version)
• ./evals/scripts/run_scenarios.sh — 15/15 (new: ambiguous-scope-refuse)
• python3 evals/scripts/test_grade_scenarios.py — OK
• Description word count 110 (gate: 40–160); gate-block md5 identical across all three files

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added clearer scope summaries to command output.
  • Improved migration guidance with a documented two-phase approval workflow.
  • Added comprehensive migration contract documentation.

• Bug Fixes

  • Ambiguous scope values and empty scope entries are now rejected with clear errors.
  • Invalid scope input no longer creates or modifies tracker files.

• Documentation

  • Updated workflow, lifecycle, terminology, and project documentation.
  • Added guidance for safer tracker migration and progressive disclosure.

• Tests

  • Expanded coverage for scope validation, output summaries, and migration scenarios.

[coderabbitai]

Warning

Review limit reached

@FWcloud916, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 24 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 98888548-a75c-46f6-8f84-53057a29ecdc

📥 Commits

Reviewing files that changed from the base of the PR and between 35c2214 and 26c897a.

📒 Files selected for processing (7)

• docs/design-decisions.md
• progress/2026-07-28-skill-docs-progressive-disclosure/PROGRESS.md
• progress/INDEX.md
• progress/_plans/skill-docs-progressive-disclosure-progress-tracker-improvement-plan.md
• skills/progress-tracker/scripts/new_progress.py
• skills/progress-tracker/scripts/test_update_progress.py
• skills/progress-tracker/scripts/update_progress.py

📝 Walkthrough

Walkthrough

The progress-tracker refactor centralizes migration guidance, revises skill operating rules, strengthens CLI scope validation and output, updates supporting documentation and evaluation coverage, records the work, and bumps plugin versions to 1.8.0.

Changes

Progress-tracker contract and scope validation

Layer / File(s)	Summary
Migration contract and authoritative references skills/progress-tracker/references/migration.md, skills/progress-tracker/references/workflow.md, README.md, agents/progress-tracker.md	Migration discovery, consent, inventory, audit, finalize commands, dispositions, and deletion rules are consolidated into migration.md; related guidance points to the contract.
Skill activation and operating rules skills/progress-tracker/SKILL.md, AGENTS.md	Activation, preflight, scaffolding, update, check, status, cleanup, and editing guidance are rewritten around progressive disclosure and delegated CLI help.
Scope parsing and CLI update flow skills/progress-tracker/scripts/new_progress.py, skills/progress-tracker/scripts/update_progress.py, skills/progress-tracker/scripts/test_*.py, evals/scenarios/ambiguous-scope-refuse/scenario.json	Ambiguous or empty scope entries are rejected, parsed scopes are echoed in normal output, update mutations reuse parsed entries, and tests cover failure atomicity and output formatting.
Supporting documentation and records docs/*, evals/README.md, progress/**	Shared vocabulary, design decisions, project references, evaluation coverage, refactor planning, and completion records are updated.
Release metadata .claude-plugin/plugin.json, .codex-plugin/plugin.json	Both plugin manifests move from version 1.7.1 to 1.8.0.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main refactor and key scope-validation/version bump changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/progress-tracker-improvement-plan-950330

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@progress/_plans/skill-docs-progressive-disclosure-progress-tracker-improvement-plan.md`:
- Around line 3-5: Reconcile the baseline line count in the plan’s opening
metadata with the 302-line starting value recorded in PROGRESS.md. Document the
intermediate 309→302 measurement and how it was obtained, or update the cited
baseline so the ≤180-line acceptance metric can be reproduced consistently.
- Around line 94-95: Update the Phase 4 plan deliverable and acceptance-table
entries referencing CONTEXT.md to point to the implemented domain-models.md
artifact, including the corresponding references in the affected sections. If
both files are intentionally required, explicitly document their distinct
responsibilities and retain both paths.

In `@progress/2026-07-28-skill-docs-progressive-disclosure/PROGRESS.md`:
- Around line 4-8: Update
progress/2026-07-28-skill-docs-progressive-disclosure/PROGRESS.md lines 4-8 to
set Status to review; replace the placeholder background and empty task list at
lines 18-25 with the actual completed record; revise lines 35-44 to remove the
premature closed-as-done claim and record the actual merged PR or commit; update
progress/INDEX.md line 13 to mirror review now and change to done only after
merge.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 68b61f1d-b102-445e-8891-1251722e9520

📥 Commits

Reviewing files that changed from the base of the PR and between 2cd0f25 and c93862e.

📒 Files selected for processing (14)

• .claude-plugin/plugin.json
• .codex-plugin/plugin.json
• AGENTS.md
• README.md
• agents/progress-tracker.md
• docs/design-decisions.md
• docs/domain-models.md
• docs/project-overview.md
• progress/2026-07-28-skill-docs-progressive-disclosure/PROGRESS.md
• progress/INDEX.md
• progress/_plans/skill-docs-progressive-disclosure-progress-tracker-improvement-plan.md
• skills/progress-tracker/SKILL.md
• skills/progress-tracker/references/migration.md
• skills/progress-tracker/references/workflow.md

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/progress-tracker/scripts/new_progress.py`:
- Around line 582-584: Update the --scope help text near parse_scope() to state
that leading, trailing, or doubled commas produce rejected empty entries.
Preserve the existing wording about unescaped commas with adjacent whitespace
and the default branch behavior.

In `@skills/progress-tracker/scripts/update_progress.py`:
- Around line 594-597: Distinguish an explicitly provided empty scope from an
omitted scope in the update command. Change both the mutation guard near the
argument validation and the scope-processing condition around parse_scope and
replace_scope_table to check args.scope is not None instead of truthiness, then
add a regression test covering update with --scope "" and --work-log, including
the expected empty-scope behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1938da9c-0bf7-422b-a488-f39a8ff825e0

📥 Commits

Reviewing files that changed from the base of the PR and between 86d2ec4 and 35c2214.

📒 Files selected for processing (10)

• docs/design-decisions.md
• docs/domain-models.md
• evals/README.md
• evals/scenarios/ambiguous-scope-refuse/scenario.json
• skills/progress-tracker/SKILL.md
• skills/progress-tracker/references/workflow.md
• skills/progress-tracker/scripts/new_progress.py
• skills/progress-tracker/scripts/test_new_progress.py
• skills/progress-tracker/scripts/test_update_progress.py
• skills/progress-tracker/scripts/update_progress.py

🚧 Files skipped from review as they are similar to previous changes (2)

• skills/progress-tracker/references/workflow.md
• docs/domain-models.md

[FWcloud916]

Addressed all 5 CodeRabbit findings in e7f7fcb:

1. Baseline 309 vs 302 — deviation record appended to the plan snapshot: 309 was measured when the plan was written (2026-07-27); main stood at 302 when execution started (2026-07-28). The ≤180 acceptance metric is evaluated against 302, matching PROGRESS.md.
2. Plan Phase 4 vs implementation — same deviation record documents the reroute from CONTEXT.md to domain-models.md §0 Shared Vocabulary, and a new docs/design-decisions.md entry records the rationale (vocabulary sits beside its entities; AGENTS.md already routes there) plus the revisit condition now that doc-architect 2.4.0 ships an opt-in CONTEXT.md module.
3. Premature done — item status is now review in both PROGRESS.md and INDEX.md; the early close is corrected by an appended work-log line (history preserved), and the Outcome links this PR.
4. --scope help wording — now says "leading, trailing, or doubled comma", matching parse_scope().
5. Explicit empty --scope silently ignored — both checks in update_progress.py use is not None, so --scope "" reaches parse_scope() and fails loudly with "produced no valid entries"; two pytest cases cover it (alone, and alongside --work-log).

Gate: verify.sh all green, uvx ruff==0.16.0 clean, pytest 193 passed.

🤖 Generated with Claude Code