Fold Insights follow-ups into CLAUDE.md, add make preflight and /ship - #82
Merged
Conversation
Adds four process rules from the 2026-09-08 Claude Code Insights report to root CLAUDE.md: a Feature Verification section (run the real command before calling a user-facing feature done), a Tooling Gotchas section (the formatter hook stripping unused-looking imports, Git Bash mangling heredocs), and a Documentation Blast Radius subsection under Documentation. The proposed "Branch & PR Workflow" section overlapped almost entirely with the same-day Branch Discipline section, so its content (the CLAUDE.md-only-edit exception, the PR/merge/cleanup steps, the make-preflight-before-commit requirement) was folded into Branch Discipline instead of duplicating it under a second heading. Adds `make preflight`: docs/inventory regeneration, the link checker, the two structural-consistency checks fast enough for a local gate (check-manifest, check-references), lint, typecheck, and the test suite -- a faster pre-commit gate than full `make ci`, which it does not replace. Adds `.claude/skills/ship/SKILL.md`, a checklist for the branch -> TDD -> blast-radius -> preflight -> ci -> PR -> merge loop that every numbered step cites back to the CLAUDE.md section it restates. Blast radius: creating `.claude/skills/` and `.claude/skills/ship/` brought the tracked CLAUDE.md count from 47 to 49, which required updating docs/planning/roadmap.md's TASK-009 row and regenerating docs/repository-inventory.md and docs/planning/status.md. While fixing that count, found and corrected two pre-existing drifts: docs/ repository-manifest.md's own copy of the same count had been stale at 45 since 2026-08-23 (two updates behind roadmap.md), and the roadmap's "N carry real content" arithmetic no longer matched its own total (44 implied, 42 stated). Both corrected in this change. make ci: 1142 passed, 21 skipped, 99% coverage; all structural checks (check-graph, check-manifest, check-references, check-scenarios, check-stages, check-documents, check-status, check-dates, check-benchmark-report) green. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
# Conflicts: # docs/planning/status.md # docs/repository-inventory.md # docs/repository-manifest.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Folds six follow-ups from the 2026-09-08 Claude Code Insights usage report into
CLAUDE.md, theMakefile, and a new/shipskill.CLAUDE.md: adds a Feature Verification Before Reporting Done section (after Merge Gate), a Tooling Gotchas section (Formatter Hook Interaction + Shell Usage/Git Bash), and a Documentation Blast Radius subsection under Documentation.Makefile: addsmake preflight— regenerates the docs index and repository inventory, then runs the link checker,check-manifest/check-references, lint, typecheck, and the test suite, failing fast. Deliberately narrower thanmake ci; not a substitute for it before merge..claude/skills/ship/SKILL.md: the/shipskill — branch → TDD → blast-radius propagation → preflight → ci → PR → merge — with every numbered step citing theCLAUDE.mdsection it restates, so the two can't quietly diverge.Blast radius
Adding
.claude/skills/and.claude/skills/ship/triggered this repo's own KA-038 rule (every directory needs aCLAUDE.md), bumping the tracked count from 47 to 49. Fixing that count surfaced and corrected two pre-existing drifts in the same commit:docs/repository-manifest.md's own copy of the CLAUDE.md count had been stale at 45 since 2026-08-23 — two updates behinddocs/planning/roadmap.md's copy.Test plan
make cigreen: 1142 passed, 21 skipped, 99% coverage; all structural checks (check-graph,check-manifest,check-references,check-scenarios,check-stages,check-documents,check-status,check-dates,check-benchmark-report) greenmake -n preflightconfirms the new target's prerequisite chain resolves correctly🤖 Generated with Claude Code