docs: codemap-audit (B.5) plan + adopt grill-me & improve-codebase-architecture skills#32
Merged
SutuSebastian merged 4 commits intomainfrom May 1, 2026
Merged
Conversation
Per docs/README.md Rule 3 (plans/<feature-name>.md, link from roadmap), draft the design pass for the highest-leverage Tier B candidate from docs/research/fallow.md before writing any code. Plan covers: - Snapshot-strategy trade-offs (worktree+full-index vs. B.6 baseline reuse vs. on-demand snapshot table) — recommends Option A (temp worktree under .codemap.audit-<sha>/) for v1; defers caching and perf optimization until a real consumer hits the wall. - Built-in deltas for v1: files, dependencies, deprecated, visibility, barrels (top-N membership change), hot files (fan-in/fan-out top-N movement). Out: cycles, boundary crossings, markers, css_*. - Verdict shape: pass/warn/fail with thresholds opt-in via codemap.config.audit; v1 emits raw deltas only (default pass). Exit codes 0/1/2 mirror `git diff --exit-code`. - Composition table: --json / --summary work; --changed-since / --group-by / --baseline are mutex (different output shapes or semantics). - Tracer-bullet sequence: 7 commits for end-to-end ship. - Open questions surfaced rather than guessed — worktree location, empty-diff warning, per-delta actions, perf ceiling. Roadmap entry added pointing at the plan; backlog item moved to top since it's now actively designed.
|
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughThis PR introduces four new agent skills ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
…mattpocock) Two Tier 3 maintainer-only skills sourced from mattpocock/skills: grill-me — pure interview pattern. Walk a design tree branch by branch, recommend an answer per question, ask one at a time. 8-line skill, zero cost when not invoked. Filled a gap visible in the codemap-audit plan (this PR's first commit): I made many decisions by myself; grill-me would have surfaced them for second opinion before they crystallised in the doc. improve-codebase-architecture — Ousterhout-style deepening vocabulary (module / interface / seam / adapter / depth / leverage / locality), the deletion test, "one adapter = hypothetical seam, two = real," dependency categories (DEEPENING.md), and parallel-sub-agent "Design It Twice" interface exploration (INTERFACE-DESIGN.md). Translated CONTEXT.md / docs/adr/ references → docs/glossary.md / docs/plans/ to fit codemap's existing docs framework (per Rule 9 + Rule 3); ADR-offer flow dropped since codemap lifts decisions from plans into architecture.md per Rule 2. Companion files (LANGUAGE.md, DEEPENING.md, INTERFACE-DESIGN.md) are verbatim — they don't reference CONTEXT.md / ADRs. Both adopted as maintainer-only (under .agents/skills/ + .cursor/skills/ symlinks per agents-first-convention). Not added to templates/agents/ since that surface ships only the codemap rule + skill — same precedent as PR #25 for audit-pr-architecture / docs-governance / etc. agents-tier-system Tier 3 list updated with both skills + the existing docs-governance and docs-lifecycle-sweep entries that were missing. Composes with grill-me from improve-codebase-architecture's grilling-loop step (deepening candidates get grilled, not auto-accepted). Skipped grill-with-docs (the third skill in the upstream "grill" family) — it requires standing up CONTEXT.md / docs/adr/ infrastructure that conflicts with codemap's lift-to-architecture-then-delete-the-plan lifecycle.
SutuSebastian
changed the title
Two more Tier 3 maintainer-only skills sourced from mattpocock/skills: diagnose — disciplined 6-phase loop for hard bugs and perf regressions (reproduce → minimise → hypothesise → instrument → fix → cleanup). Core thesis: "build the right feedback loop, and the bug is 90% fixed." Translation: explore-the-codebase step now points at codemap (per the codemap rule's STOP-before-grep) and docs/glossary.md (per Rule 9 canonical terms); ADR mention dropped (no ADR infra in this repo); Phase-5 seam discipline cross-references improve-codebase-architecture (adopted in 906ecba); Phase-6 cleanup includes a one-line lessons.md append per the lessons-rule discipline. scripts/hitl-loop.template.sh ships verbatim — no codemap-specific assumptions. write-a-skill — meta-skill for creating new skills. Translation: front section explicitly cites our agents-first-convention (file layout) and agents-tier-system (tier choice + durability), plus the maintainer-only-vs-shipped distinction (precedent: PR #25). Examples cite codemap precedents (improve-codebase-architecture for the companion-files split; pr-comment-fact-check for single-file). Review checklist adapted: tier choice + rule-pairing decision + tier-list update added. Both adopted as maintainer-only (.agents/skills/ + .cursor/skills/ symlinks per agents-first-convention). Not added to templates/agents/ — consumer surface stays codemap-skill-only. agents-tier-system Tier 3 list updated: diagnose, write-a-skill added (alongside grill-me + improve-codebase-architecture from the prior commit). Skipped grill-with-docs (requires standing up CONTEXT.md / docs/adr/ infra; conflicts with codemap's lift-to-architecture-and- delete-the-plan lifecycle).
…olved)
Used the just-adopted grill-me skill against the plan to surface
decisions I'd waved away in the first draft. Eight Qs walked, all
agreed answers written into the plan inline (per grill-me discipline).
Q1 Snapshot strategy → ship BOTH modes; v1 = --baseline <name>
(B.6 reuse), v1.x = --base <ref> (worktree+reindex). Mutex.
Was: Option A only. Now: both shipped, B first because it's the
real use case (delta-against-saved-state) and reuses existing
infra without worktree code.
Q2 Built-in deltas → 3 deltas in v1 (files / dependencies /
deprecated), not 6. visibility / barrels / hot_files / cycles /
boundary_crossings / markers / css_* deferred with explicit
triggers to revisit. Was: padding the v1 surface.
Q3 Verdict shape → DROPPED from v1 entirely. No `verdict` field, no
exit codes 1/2, no codemap.config.audit schema. Raw deltas only.
Consumers compose --json + jq for CI exit codes; v1.x ships
verdict + thresholds when real consumer config patterns emerge.
Was: opt-in thresholds with always-pass default (placeholder).
Q4 Diff identity → each delta defines its own canonical projection
(fixed SELECT … ORDER BY) and validates baseline column-set
membership before diffing. Baseline's stored `sql` is informational.
Isolates audit from underlying-table schema drift (e.g. the v4→v5
visibility column bump).
Q5 Terminal output → `git status`-style: terse on no-drift, per-delta
tables only when non-empty. --summary collapses to one line.
Mirrors the JSON shape with row-arrays-vs-counts distinction.
Q6 File layout → split src/cli/cmd-audit.ts (CLI) + src/application/
audit-engine.ts (engine). Mirrors existing cmd-index.ts ↔
index-engine.ts seam. Engine testable independent of CLI shape;
v1.x --base <ref> slice becomes mechanical.
Q7 Same-SHA warning → NO. Renderer's metadata header already exposes
baseline.git_ref so user can spot the case. Adding a heuristic
warning would be noise + meaningful code for low signal. Settled
open question struck from §9.
Q8 Index freshness → audit auto-runs `runCodemapIndex({mode:
"incremental"})` as a prelude. Same discipline as the codemap
rule's "re-index after editing source." Sub-second when no source
changed. --no-index opts out for the rare frozen-DB CI case.
Net result: v1 is meaningfully smaller (3 deltas, no verdict, no
schema additions, no worktree code) and ships faster (~½ day across
~6 commits). Each deferred piece has an explicit trigger so the
deferral isn't open-ended hand-waving.
7 tasks
This was referenced May 1, 2026
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.
Two unrelated docs changes batched:
1. Plan:
codemap audit --base <ref>(B.5)Per
docs/README.mdRule 3 (plans live inplans/<feature-name>.md, link fromroadmap.md), drafts the design for B.5 before writing any code. The research note explicitly calls this "the single highest-leverage candidate this refresh.".codemap.audit-<sha>/(gitignored by the existing.codemap.*glob). Defers caching / perf-tuning until a real consumer hits the wall.files,dependencies,deprecated,visibility,barrels,hot_files. Each wraps an existing recipe — no new analysis layer.pass/warn/failwith thresholds opt-in viacodemap.config.audit. v1 emits raw deltas only (defaultpass).0/1/2— mirrorsgit diff --exit-code.--json/--summarywork;--changed-since/--group-by/--save-baseline/--baselineare mutex (different shapes / semantics).Both prerequisites just merged on
main: B.6 (PR #30) proves the snapshot-in-DB primitive; B.7 (PR #28) provides thesymbols.visibilitycolumn thevisibilitydelta needs.2. Adopt two Tier 3 skills from
mattpocock/skillsSourced after evaluating three skills mid-thread; the two adopted ones earn their always-zero-cost slot:
grill-megrill-mewould have surfaced them for second opinion before they crystallised.improve-codebase-architecturemodule / interface / seam / adapter / depth / leverage / locality), the deletion test, "one adapter = hypothetical seam, two = real," dependency categories (DEEPENING.md), and parallel-sub-agent "Design It Twice" interface exploration (INTERFACE-DESIGN.md).Both are maintainer-only (under
.agents/skills/+.cursor/skills/symlinks peragents-first-convention). Not added totemplates/agents/— same precedent as PR #25 (consumer surface ships only the codemap rule + skill).Translation notes
improve-codebase-architecture/SKILL.mdadapted at three points to fit codemap's docs framework (the upstream version assumesCONTEXT.md+docs/adr/; we have neither):CONTEXT.mdreferences →docs/glossary.md(Rule 9 already enforces glossary updates per PR).docs/adr/references →docs/plans/<topic>.md(Rule 3 — but plans are mortal; decisions of record lift toarchitecture.mdper Rule 2 then the plan is deleted).Companion files (
LANGUAGE.md,DEEPENING.md,INTERFACE-DESIGN.md) ship verbatim — none referenceCONTEXT.mdor ADRs.grill-me/SKILL.mdextended with two short codemap-specific notes: prefercodemapoverGrepwhen exploring (per thecodemaprule), and write crystallised answers into the in-flightdocs/plans/<name>.mdinline (Rule 3).Skipped
grill-with-docs(the third skill in the upstream "grill" family) — requires standing up CONTEXT.md /docs/adr/infrastructure that conflicts with the lift-to-architecture-then-delete-the-plan lifecycle codemap already runs. The salvageable ADR 3-criteria gate is recorded in this conversation; lift if codemap ever needs ADRs.Tier 3 list updated
.agents/rules/agents-tier-system.mdTier 3 list extended with both new skills, and the previously-missingdocs-governance+docs-lifecycle-sweepentries from PR #25.Test plan
bun run checkgreen (no behavior changed; pure docs + skills)..cursor/skills/{grill-me,improve-codebase-architecture}symlinks resolve.docs/README.md § Document Lifecycle— delete on ship, lift toarchitecture.md.Summary by CodeRabbit
Release Notes
New Features
diagnoseskill for structured debugging and performance regression analysis.grill-meskill for interactive step-by-step decision-tree interviews.improve-codebase-architectureskill for identifying and deepening module designs.write-a-skillskill for authoring new agent capabilities.Documentation
codemap auditcommand.