fix(done-check,todo-check,quality-list): derive item set from index

[ultimatile]

Summary

docstring-drift was defined in quality-list but audited by neither runner, because done-check and todo-check hardcoded parallel item lists that drifted from the index. The duplication was an incidental side effect of an earlier change (b36ea8e) that moved item bodies out of main context: it correctly dropped the bodies but hand-copied the enumeration into each runner, when the short index already held it. This makes the quality-list Items index the single source of truth for item enumeration and lane, and both runners now derive their active set from it. Item bodies are still not loaded into main context — only the index is.

Closes #44

Changes

• quality-list/SKILL.md: declare the Items index authoritative for which items exist and their lane (not only item-body text); item files no longer carry an H1 lane tag.
• quality-list/items/*.md: remove the [mechanical] / [contextual] suffix from every item's H1 heading, so the lane lives only in the index.
• done-check: the Step 2 mechanical subagent and the Step 3 contextual main-context audit both select their item set from the index by lane; the output table is trimmed to illustrative rows emitted one-per-index-item.
• todo-check: the index is the authoritative spine walked in preflight; the quick reference is reframed as an accelerator over it, with a safe fallback that reads an item file when an index item lacks a quick-reference entry, plus a new docstring-drift entry.

Impact

Runner behaviour — audit every quality-list item — is unchanged, except that docstring-drift is now covered and the active set can no longer drift from the index. No other skill enumerates the item list (consumers reference items by single slug), so nothing else is affected.

Test plan

These are prompt / markdown skills, so there is no executable suite. Verified by deriving the lanes from the index: the mechanical lane resolves to 9 items (matching done-check's prior hardcoded list) and the contextual lane to 9 (the prior 8 plus the previously-missing docstring-drift); the dual-lane ported-code-attribution lands in both lanes via its mechanical (+ contextual half) index tag. mdformat runs clean. A done-check pass over this diff dogfooded the new derivation — the mechanical subagent selected its items from the index, and docstring-drift was audited as a contextual item.

Notes

The compressed-lens text in todo-check's quick reference is still hand-maintained and can drift from the item bodies — a content axis distinct from the enumeration drift fixed here. If that becomes a problem, each item's one-line preflight framing would move into its item file so todo-check derives the lens content too.

Summary by CodeRabbit

• Documentation
  • Clarified how the quality-check guides are organized and consumed, including the canonical item index and lane handling.
  • Updated several checklist item titles for consistency and removed outdated lane annotations.
  • Expanded guidance for audit workflows and refreshed example output entries.
• Chores
  • Bumped the marketplace version to the latest patch release.

[coderabbitai]

📝 Walkthrough

Walkthrough

Bumped the marketplace metadata version and updated quality-list docs to treat the Items index as the source of truth for lanes and item coverage. Done-check and todo-check now derive their item sets from that index, and todo-check adds docstring-drift coverage.

Changes

Marketplace metadata bump

Layer / File(s)	Summary
Version bump .claude-plugin/marketplace.json	version changes from 2026.6.41 to 2026.6.42.

Quality-list audit docs

Layer / File(s)	Summary
Items index and headings skills/quality-list/SKILL.md, skills/quality-list/items/*	The quality-list SSOT text names the Items index as canonical for item presence and lane assignment, and item headings remove lane annotations or placeholder qualifiers.
Escape-hatch necessity skills/quality-list/items/escape-hatch-necessity.md	The escape-hatch necessity item adds criteria for when an escape hatch is acceptable, a framing-error warning, trigger guidance, concern conditions, and irreducible boundary-case exclusions.
done-check index selection skills/done-check/SKILL.md	Step 2 and Step 3 select mechanical and contextual items from the Items index, and the output example table shows behavior-coverage, test-execution, docstring-drift, and ported-code-attribution.
todo-check index spine skills/todo-check/SKILL.md	Step 2 treats the Items index as authoritative, falls back to full item bodies when quick-reference coverage is missing or insufficient, updates the quick-reference framing, and adds docstring-drift.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• quality-list: item add/remove has no paired-surface sync checklist #16: Adds the missing docstring-drift quick-reference entry and routes both runners through the Items index, matching the auditing gap described here.

Possibly related PRs

• ultimatile/development-skills#17: Updates the same quality-list SSOT and done-check lane-selection mechanics that this PR builds on.
• ultimatile/development-skills#33: Touches the same todo-check preflight and implementation-guard guidance surfaces referenced in this PR.

Poem

A rabbit hopped through docs so bright,
The index led the lanes just right.
Docstring drift joined the audit song,
And headings shed their tags all along.
🐇✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The marketplace version bump in .claude-plugin/marketplace.json is unrelated to the audit/index changes in #44.	Move the version bump to a separate release PR, or justify it in the change scope if it is required here.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: deriving item sets from the index for done-check and todo-check.
Linked Issues check	✅ Passed	[#44] The runners now derive enumeration from the index and include docstring-drift in the audited surfaces.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/44-quality-list-ssot

---

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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

skills/quality-list/items/escape-hatch-necessity.md (1)

3-7: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Clarify the parenthetical examples to be more language-agnostic.

The parenthetical (trait dispatch, generics, enum) in line 11 uses Rust-centric terminology. While language-specific addenda exist, the base item's examples should be more universally recognizable or explicitly marked as illustrative.

Consider rephrasing to broaden the examples or add a clarifying phrase:

- Diff adds an escape hatch to convert between types a safe construct (trait dispatch, generics, enum) could keep concrete at the use site
+ Diff adds an escape hatch to convert between types a safe construct (trait dispatch / interface method, generics / templates, enum / discriminated union / std::variant) could keep concrete at the use site

Or more minimally:

- Diff adds an escape hatch to convert between types a safe construct (trait dispatch, generics, enum) could keep concrete at the use site
+ Diff adds an escape hatch to convert between types a safe construct (e.g., trait dispatch, generics, enum — or their language equivalents) could keep concrete at the use site

🤖 Prompt for 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.

In `@skills/quality-list/items/escape-hatch-necessity.md` around lines 3 - 7, The
parenthetical examples in the escape-hatch necessity guidance are too
Rust-centric, so update the wording in the quality-list item to use more
language-agnostic examples or explicitly mark them as illustrative. Keep the
intent in the paragraph about safe alternatives by rephrasing the concrete-type
examples around the existing “trait / interface dispatch, generics, an enum”
language so it reads universally across languages while preserving the same
guidance.

🤖 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.

Outside diff comments:
In `@skills/quality-list/items/escape-hatch-necessity.md`:
- Around line 3-7: The parenthetical examples in the escape-hatch necessity
guidance are too Rust-centric, so update the wording in the quality-list item to
use more language-agnostic examples or explicitly mark them as illustrative.
Keep the intent in the paragraph about safe alternatives by rephrasing the
concrete-type examples around the existing “trait / interface dispatch,
generics, an enum” language so it reads universally across languages while
preserving the same guidance.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4ab2715e-2b75-4cd1-aad9-65fc8530c7b2

📥 Commits

Reviewing files that changed from the base of the PR and between 15151ae and 3d6a63f.

📒 Files selected for processing (22)

• .claude-plugin/marketplace.json
• skills/done-check/SKILL.md
• skills/quality-list/SKILL.md
• skills/quality-list/items/architectural-boundary.md
• skills/quality-list/items/behavior-coverage.md
• skills/quality-list/items/completion-hygiene.md
• skills/quality-list/items/discovery-surfacing.md
• skills/quality-list/items/docstring-drift.md
• skills/quality-list/items/escape-hatch-necessity.md
• skills/quality-list/items/impact-verification.md
• skills/quality-list/items/implementation-guards.md
• skills/quality-list/items/invariant-derivation.md
• skills/quality-list/items/paired-artifact-drift.md
• skills/quality-list/items/pattern-audit.md
• skills/quality-list/items/ported-code-attribution.md
• skills/quality-list/items/public-api-surface.md
• skills/quality-list/items/public-doc-durability.md
• skills/quality-list/items/purpose-verification.md
• skills/quality-list/items/scope-discipline.md
• skills/quality-list/items/signature-change-regression.md
• skills/quality-list/items/test-execution.md
• skills/todo-check/SKILL.md