create-suggestion

Create Suggestion

Analyze session data to detect structural issues and create proposal files requiring user approval before applying.

Qualification Criteria

Structural problems evidenced by session data:

• File bloat: A file is read frequently but only small portions used per session (low signal ratio)
• Pattern fragmentation: Multiple files doing the same thing differently
• Directory misorganization: Logically related files scattered across directories
• Missing abstractions: Same code pattern repeated in 3+ places without extraction

Evidence Requirements

Every suggestion MUST include:

• Quantitative metrics (signal ratio, read count vs edit count, etc.)
• Specific session IDs as evidence

Output Format

Create files in .claude-auto-context/suggestions/ as suggestion-YYYYMMDD-HHMMSS-{slug}.md:

# Suggestion: {title}

## Description
{one-line summary — used for deduplication and context display}

## Status
pending

## Created
{ISO 8601 UTC timestamp, e.g. 2026-03-27T14:30:52Z}

## Category
{ai-unfriendly-large-file | ai-unfriendly-naming | ai-unfriendly-missing-docs | ai-unfriendly-structure | ai-unfriendly-fragile}

## Problem
{Description with quantitative evidence and specific file names}

## Related Files
- {file1.ext} — {why this file is involved}
- {file2.ext} — {why this file is involved}

## Proposal

### Read first
- {file1.ext} — {why executor must read this before changes, e.g. "contains function to extract"}
- {file2.ext} — {dependency or convention reference}

### Files to modify
- {file1.ext} — {what changes in this file}
- {file2.ext (new file)} — {what this new file will contain}

### Changes
1. In {file1.ext}, function `{functionName}` (lines ~{N}-{M}):
   - {specific operation: extract, rename, move, delete, modify}
   - {import/export updates needed after the change}
2. In {file2.ext (new file)}:
   - Create with exports: {exportName1}, {exportName2}
   - Import dependencies: {dep1} from {source}

### Impact
- {other-file.ext} — imports from {file1.ext}, import path may need update
- {test-file.ext} — test assertions may reference moved functions

### Acceptance criteria
- [ ] `grep -q '{exportName}' {new-file.ext}` — export exists in new location
- [ ] `grep -q 'from.*{new-file}' {file1.ext}` — import path updated
- [ ] No TypeScript/syntax errors in modified files
- [ ] Existing tests pass without modification (or test updates documented)

## Evidence Sessions
- session_{id} ({date}): {what was observed}

## Metrics
- Signal ratio: {X}%
- Sessions affected: {N}/{total}
- Estimated impact: {description}