Repository navigation
Add repo-surveyor plugin: three staff-level survey lenses - #21
Merged
Merged
Conversation
A new multi-tool plugin published to Claude Code, Cursor, and Codex from one shared component tree, following the repo's parallel-catalog / version-locked / one-tree conventions. repo-surveyor scouts a codebase across three read-only "scout -> evidence-cited findings report" lenses. Every finding cites a path:line, symbol, or commit (nothing invented); LOE/benefit/severity are labeled ordinal estimates, not disguised facts; each recommendation states the trade-off both ways; findings rank by leverage. Skills (each an orchestrator SKILL.md + a read-only advisory subagent): - debt-radar: technical debt (swallowed/silenced errors, dead code, smells, brittle logic, duplication, contradiction-with-intent, latent risk), with a scan mode and a tracker-agnostic verify mode that re-checks whether a prior finding or pasted issue is resolved against current code. Agents: debt-scout, resolution-verifier. - feature-gap: maps the user-facing surface (UI routes, MCP tool schemas, CLI, public/exported API) for gaps, inconsistencies, low discoverability, recommended features, and product metrics. Agent: surface-mapper. - signal-map: recommends surgical log/metric/trace placement at error branches, hot paths, and feature boundaries. Agent: instrumentation-scout. Shared discipline: an RS Floor / RS-N Norms governance set, a severity rubric that detects the repo's own priority system (else Eisenhower -> P0-P3), and one committable config (.agents/repo-surveyor.json) with a first-run output-dir interview and scratch mode. The two metric-touching lenses split by audience (feature-gap = product metrics, signal-map = instrumentation placement) and cross-reference rather than overlap. Also ships a committed `claude plugin eval` regression suite (one case per skill, each scaffolding a fixture with a known defect and grading skill-firing, read-only posture, and report quality) and a stdlib validate.py --self-test that keeps manifests, frontmatter, shared-copy parity, agent wiring, and the eval files well-formed in the existing zero-dependency CI. Registered in all three catalogs and the top-level README; full validation suite green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KRZwiE8JHhPAemUXTXHL6n
Both metric-touching lenses shared the phrase "what should we measure" at the trigger layer, so a context-free "what metrics should I track?" was ambiguous between them. Anchor each to its side of the audience seam: - feature-gap: "which product or engagement metrics to track" (what/why) - signal-map: "where in the code to place a metric/log/trace to measure a feature's performance" (placement) Description-only wording change, folded into the unreleased 0.1.0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KRZwiE8JHhPAemUXTXHL6n
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
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.
What this adds
A new multi-tool plugin,
repo-surveyor, published to Claude Code, Cursor, and Codex from one shared component tree. It scouts a codebase across three read-only "scout → evidence-cited findings report" lenses — the same idiom ascontext-forge/design-buddy.Every finding cites a
path:line, symbol, or commit (nothing invented); LOE/benefit/severity are labeled ordinal estimates, never disguised facts; each recommendation states the trade-off both ways; findings rank by leverage.The three lenses
debt-radarscanmode and a tracker-agnosticverifymode that re-checks whether a prior finding or pasted issue is resolved against current code.debt-scout,resolution-verifierfeature-gapsurface-mappersignal-mapinstrumentation-scoutShared discipline
RSFloor /RS-NNorms governance set (byte-identical across all three skills; enforced byvalidate.py), in the spirit ofcontext-forge'sCF-*.CONTRIBUTING,P0/S1/sev*conventions), falling back to an Eisenhower (urgent × important) → P0–P3 mapping..agents/repo-surveyor.jsonwith a first-run output-dir interview (.repo-surveyor/,docs/repo-surveyor/, or a detected docs dir) and a scratch mode that writes nothing.feature-gap= product metrics,signal-map= instrumentation placement) and cross-reference rather than overlap.Testing & validation
claude plugin evalregression suite (evals/) — one case per skill, each scaffolding a fixture repo with a known defect and grading (1) the right skill fired, (2) the run stayed read-only, (3) the report meets the Floor. Because an eval run is a real billed model call, it is run on demand, not wired into the zero-dependency CI (seeevals/README.mdfor an opt-in, secret-gated CI snippet).scripts/validate.py --self-testkeeps manifests, frontmatter, shared-copy parity, agent wiring, and the eval files well-formed inside the existing free CI..claude-plugin/.cursor-plugin/.agents/plugins) and the top-levelREADME.md.validate_manifests.py --self-test+validate_manifests.py, the edit-hook self-test, and all three per-pluginvalidate.py(--self-test+ real run).Starts at
0.1.0(byte-identical across manifests). No source-mutating behavior — all three skills are read-only surveys.🤖 Generated with Claude Code
https://claude.ai/code/session_01KRZwiE8JHhPAemUXTXHL6n
Generated by Claude Code