---
name: config-audit:feature-gap
description: Context-aware feature recommendations — what could enhance your setup and why
argument-hint: "[path]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, AskUserQuestion
model: opus
---

# Config-Audit: Feature Opportunities

Context-aware analysis of Claude Code features that could benefit your specific project — with the option to implement selected recommendations on the spot.

## What the user gets

- Project context detection (language, size, existing configuration)
- Numbered recommendations grouped by impact (high / worth considering / explore)
- Each recommendation backed by evidence (Anthropic docs, proven issues)
- **Interactive selection: "Which would you like to implement?"**
- Direct implementation with backup for selected items

## Implementation

### Step 1: Determine target and greet

Parse `$ARGUMENTS` for a path (default: current working directory).

Tell the user:

```
## Feature Opportunities

Analyzing which Claude Code features could benefit your workflow...
```

### Step 2: Create session and run posture

Generate session ID (`YYYYMMDD_HHmmss`) if no active session exists.

```bash
mkdir -p ~/.claude/config-audit/sessions/{session-id}/findings 2>/dev/null
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --json --output-file ~/.claude/config-audit/sessions/{session-id}/posture.json 2>/dev/null; echo $?
```

If exit code is non-zero: "Assessment couldn't run. Check that the path exists and contains configuration files."

### Step 3: Read posture data and detect project context

Read `~/.claude/config-audit/sessions/{session-id}/posture.json` using the Read tool.

Extract GAP findings from `scannerEnvelope.scanners` (find scanner with `scanner === 'GAP'`).

Detect project context:
```bash
test -f <target-path>/package.json && echo "has_package_json" || echo "no_package_json"
ls <target-path>/*.py <target-path>/requirements.txt <target-path>/pyproject.toml 2>/dev/null | head -3
```

### Step 4: Build numbered recommendations

Read `${CLAUDE_PLUGIN_ROOT}/knowledge/gap-closure-templates.md` for implementation templates.

Group GAP findings into three sections. Number them sequentially across sections:

```markdown
### High Impact

These address correctness or safety — consider them seriously.

**1.** Add permissions.deny for sensitive paths
  → Settings enforcement is stronger than CLAUDE.md instructions.
  → Effort: Low (5 min)

**2.** Configure at least one hook for safety automation
  → Hooks guarantee the action happens. CLAUDE.md instructions are advisory.
  → Effort: Medium (15 min)

### Worth Considering

These improve workflow efficiency for projects like yours.

**3.** Split CLAUDE.md into focused modules with @imports
  → Files over 200 lines degrade Claude's adherence to instructions.
  → Effort: Low (10 min)

**4.** Add path-scoped rules for different file types
  → Unscoped rules load every session regardless of relevance.
  → Effort: Low (10 min)

### Explore When Ready

Nice-to-have. Skip if your current setup works well.

**5.** Custom keybindings (Shift+Enter for newline)
  → Effort: Low (2 min)

**6.** Status line configuration
  → Effort: Low (2 min)
```

Each recommendation MUST have:
- A number
- A one-line description
- A "Why" with evidence
- An effort estimate from the templates

### Step 5: Ask what to implement

```
AskUserQuestion:
  question: "Which would you like to implement? I'll create a backup first."
  options:
    - "All high impact (1-2)"
    - "Pick specific: e.g. 1,3,5"
    - "None — just wanted to see the recommendations"
```

If "None": show the full report location and exit.

If the user picks numbers: parse the selection and proceed to Step 6.

### Step 6: Implement selected recommendations

For each selected recommendation:

1. **Create backup** of any files that will be modified:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <target-path> --json 2>/dev/null
```
Or create manual backup:
```bash
mkdir -p ~/.claude/config-audit/backups/$(date +%Y%m%d_%H%M%S)/files/ 2>/dev/null
```
Copy each file that will be touched.

2. **Apply the template** from gap-closure-templates.md. Use the Write or Edit tool to create or modify the relevant configuration file.

3. **Show progress** as each item is done:
```
Implementing 3 recommendations...

✓ 1. permissions.deny — added to .claude/settings.json
✓ 3. Modular CLAUDE.md — created .claude/rules/testing.md, added @import
✓ 5. Keybindings — created ~/.claude/keybindings.json
```

4. **Verify** by re-running posture:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/posture.mjs <target-path> --json --output-file /tmp/config-audit-verify-$$.json 2>/dev/null
```

### Step 7: Show results

```markdown
### Done

**{N} recommendations implemented** | Backup created

{If health grade changed:}
Health: {old_grade} → {new_grade} (+{delta} points)

{Show remaining opportunities if any:}
{remaining} more opportunities available — run `/config-audit feature-gap` again anytime.

**Rollback:** If anything looks wrong, run `/config-audit rollback` to restore.
```

## Implementation Guidelines

When implementing recommendations, be smart about context:

- **permissions.deny**: Look at the project for common sensitive paths (`.env`, `secrets/`, `.git/config`, `*.pem`). Don't just copy a template blindly — check what actually exists.
- **hooks**: Start with a simple, useful hook. Don't scaffold 5 hooks at once.
- **path-scoped rules**: Look at the project's file structure to determine meaningful scopes (e.g., `tests/**/*.ts` vs `src/**/*.ts`).
- **CLAUDE.md modularization**: Only suggest splitting if the file is over 100 lines. Read it first to find natural section boundaries.
- **MCP setup**: Only relevant if the user actually has external tools to connect. Ask before creating.
- **Custom plugin**: Too complex for inline implementation — suggest `/config-audit plan` instead.

For items that genuinely need user input (e.g., "which MCP servers do you use?"), ask briefly during implementation rather than skipping them.

## Safety

- **Backup mandatory** — always create before modifying
- **Show what's changing** — the user sees each change as it happens
- **Rollback available** — `/config-audit rollback` at any time
- **Non-destructive** — only create new files or add to existing; never delete content
