6f38a6340e
Wave 5 Step 14. Threads the humanizer vocabulary through the remaining
six audit/analysis command templates and adds a shape test that locks
the structure plus a pair of anchor must-contains.
- commands/drift.md: --raw pass-through; new/resolved/changed-finding
rendering instructions reference userActionLanguage and
relevanceContext rather than raw severity.
- commands/plugin-health.md: --raw pass-through; finding rendering
groups by userImpactCategory and leads with userActionLanguage.
- commands/config-audit.md (router): replaces the 25-line A/B/C/D/F
prose ladder with a humanized stderr-scorecard reference + three
userActionLanguage-grouped "What you can do next" branches; --raw
threaded through both scan-orchestrator and posture invocations.
- commands/discover.md: --raw pass-through; finding-summary rendering
groups by userImpactCategory.
- commands/analyze.md: --raw pass-through; analyzer-agent prompt now
instructs grouping by userImpactCategory and leading with
userActionLanguage; humanized title/description/recommendation
strings rendered verbatim, no paraphrasing.
- commands/status.md: phase-label humanization table — current_phase
machine field name preserved, user-facing labels translated
("Looking at your config files", "Working out what to recommend",
"Asking what you'd like to focus on", "Putting together your action
plan", "Making the changes", "Double-checking everything worked");
--raw preserves verbatim machine field values.
tests/commands/group-b-shape.test.mjs (new, +8 tests, 772 → 780):
- structural: bash block + Read tool + --raw/$ARGUMENTS plumbing
across all 6 files
- findings-renderers: humanized field reference + no grade-prose
- anchor must-contains per plan: config-audit.md ⊇
userImpactCategory|userActionLanguage; drift.md ⊇ --raw|humanized
- status.md: current_phase preserved + ≥3 humanized phase labels
143 lines
5 KiB
Markdown
143 lines
5 KiB
Markdown
---
|
|
name: config-audit:discover
|
|
description: Phase 1 - Initialize session, auto-detect scope, and discover config files
|
|
argument-hint: "[current|repo|home|full] [--delta]"
|
|
allowed-tools: Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion, Bash
|
|
model: opus
|
|
---
|
|
|
|
# Config-Audit: Discover (Phase 1)
|
|
|
|
Initialize a new audit session and discover all Claude Code configuration files.
|
|
|
|
## Usage
|
|
|
|
```
|
|
/config-audit discover # Auto-detect scope
|
|
/config-audit discover current # Force current directory scope
|
|
/config-audit discover repo # Force git repository scope
|
|
/config-audit discover home # Force home/global scope
|
|
/config-audit discover full # Force full machine scope
|
|
/config-audit discover --delta # Incremental re-scan (changed files only)
|
|
```
|
|
|
|
## Implementation
|
|
|
|
### Step 1: Initialize session and greet
|
|
|
|
Generate session ID (`YYYYMMDD_HHmmss`), create directories:
|
|
|
|
```bash
|
|
mkdir -p ~/.claude/config-audit/sessions/{session-id}/findings 2>/dev/null
|
|
```
|
|
|
|
### Step 2: Determine scope
|
|
|
|
If the user provided a scope argument, use it. Otherwise, auto-detect:
|
|
1. Run `git rev-parse --show-toplevel 2>/dev/null`
|
|
2. If inside a git repo → **repo** scope
|
|
3. If pwd is `$HOME` → **home** scope
|
|
4. Otherwise → **current** directory scope
|
|
|
|
Tell the user:
|
|
|
|
```
|
|
## Configuration Discovery
|
|
|
|
**Scope:** {Repository|Home|Current directory|Full machine} — `{path}`
|
|
Finding all Claude Code configuration files (CLAUDE.md, settings, hooks, rules, MCP servers)...
|
|
```
|
|
|
|
### Step 3: Resolve paths
|
|
|
|
| Scope | What gets scanned |
|
|
|-------|-------------------|
|
|
| `current` | Current directory + parent CLAUDE.md files up to root + `~/.claude/` |
|
|
| `repo` | Git repo root + `~/.claude/` |
|
|
| `home` | `~/.claude/` only |
|
|
| `full` | `~/.claude/` (depth 10), managed paths, all dev dirs under $HOME |
|
|
|
|
### Step 4: Delta mode (if --delta)
|
|
|
|
If `--delta` flag:
|
|
1. Find previous baseline from `~/.claude/config-audit/sessions/*/discovery.json`
|
|
2. If no previous: "No previous scan found. Running full discovery instead."
|
|
3. Compare file mtimes/sizes to classify as changed/new/deleted/unchanged
|
|
4. Only scan changed + new files
|
|
|
|
### Step 5: Run discovery
|
|
|
|
Run the scan orchestrator silently to discover and scan files. Default mode emits humanized JSON — each finding in `scan-results.json` carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields. Pass `--raw` through if the user requested it (produces v5.0.0 verbatim envelope; humanizer fields absent).
|
|
|
|
```bash
|
|
RAW_FLAG=""
|
|
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
|
|
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <target-path> --output-file ~/.claude/config-audit/sessions/{session-id}/findings/scan-results.json [--full-machine] [--global] $RAW_FLAG 2>/dev/null; echo $?
|
|
```
|
|
|
|
Check exit code: 0/1/2 → normal. 3 → "Discovery encountered an error. Try a narrower scope."
|
|
|
|
### Step 6: Save scope and state
|
|
|
|
Write `scope.yaml` and `state.yaml` to session directory. Update state with `current_phase: "discover"`, `next_phase: "analyze"`.
|
|
|
|
### Step 7: Present summary
|
|
|
|
Read the scan results file using the Read tool. When you surface initial findings, group them by `userImpactCategory` and lead each line with `userActionLanguage` rather than raw severity prefiks — the humanizer already mapped severity to plain-language phrasing ("Fix this now", "Fix soon", "Fix when convenient", "Optional cleanup", "FYI") so the rest of the toolchain sees consistent wording.
|
|
|
|
**Full scan:**
|
|
```markdown
|
|
### Discovery Complete
|
|
|
|
**{scope_type}** scope — found {total_files} configuration files:
|
|
|
|
| Type | Count |
|
|
|------|-------|
|
|
| CLAUDE.md | {n} |
|
|
| Settings | {n} |
|
|
| MCP configs | {n} |
|
|
| Rules | {n} |
|
|
| Hooks | {n} |
|
|
| Other | {n} |
|
|
|
|
Initial scan found {finding_count} items to review (grouped by impact: {comma-separated counts per userImpactCategory}).
|
|
|
|
**Next:** Run `/config-audit analyze` to generate your analysis report.
|
|
```
|
|
|
|
**Delta scan:**
|
|
```markdown
|
|
### Delta Discovery Complete
|
|
|
|
Compared against baseline from {previous-session-id}:
|
|
|
|
| Status | Files |
|
|
|--------|-------|
|
|
| Changed | {n} |
|
|
| New | {n} |
|
|
| Deleted | {n} |
|
|
| Unchanged | {n} |
|
|
|
|
Only {changed+new} file(s) scanned (vs {total} full scan).
|
|
|
|
**Next:** Run `/config-audit analyze` to generate your analysis report.
|
|
```
|
|
|
|
## Config File Patterns
|
|
|
|
| Pattern | Description |
|
|
|---------|-------------|
|
|
| `**/CLAUDE.md` | Project instructions |
|
|
| `**/CLAUDE.local.md` | Local overrides |
|
|
| `**/.claude/settings.json` | Project settings |
|
|
| `**/.mcp.json` | MCP servers |
|
|
| `**/.claude/rules/*.md` | Modular rules |
|
|
|
|
For global: `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude.json`, `~/.claude/agents/*.md`
|
|
|
|
## Error Handling
|
|
|
|
- If scanner fails, report to user in plain language and suggest narrower scope
|
|
- If path doesn't exist, tell user and suggest alternatives
|
|
- If git command fails for `repo` scope, silently fall back to `current`
|
|
- If no config files found, explain: "No Claude Code configuration files found. Start with `/config-audit feature-gap` to see what's recommended."
|