instruction-advisor

Instruction Advisor

Perform a comprehensive review of the project's instruction files, combining convention discovery, static quality analysis, and conformance checking into a single actionable report.

Process

Phase 1: Discovery

Find all instruction files in the project:

• CLAUDE.md and .claude.local.md
• .claude/rules/*.md
• .claude/agents/*.md
• .claude/skills/*/SKILL.md
• .cursorrules, AGENTS.md (if present)

Note which files exist and their approximate size.

Phase 2: Static Quality Analysis

Call alignkit_local_lint first (bundled server, no external dependency). If unavailable, fall back to alignkit_lint (external server). If BOTH are unavailable, you MUST perform manual lint analysis — this phase cannot be skipped:

1. Find instruction files using Glob: CLAUDE.md, .claude/rules/**/*.md, .claude/agents/**/*.md, .claude/skills/**/SKILL.md
2. Read each file and parse rules (lines starting with -, *, or N. under headings). Strip YAML frontmatter first.
3. Collect project context: read package.json for dependencies, tsconfig.json for config, list top-level directories.
4. Run manual diagnostics on each rule:
   • VAGUE: "try to", "when possible", "generally", "consider", "as needed"
   • CONFLICT: "always X" paired with "never X" where X overlaps
   • REDUNDANT: >70% word overlap between two rules
   • ORDERING: tool constraints appearing after style rules (within same file)
   • PLACEMENT: file-pattern rules in CLAUDE.md (belong in .claude/rules/) or automation rules (belong as hooks)
   • WEAK_EMPHASIS: tool constraints missing MUST/NEVER/ALWAYS markers
   • LINTER_JOB: formatting rules that should be enforced by a linter/formatter (indentation, semicolons, import sorting, trailing commas)
   • METADATA: agent/skill files missing required frontmatter fields

The primary instruction file is the project root CLAUDE.md (or the single instruction file if only one exists). When multiple files exist, analyze all of them but present CLAUDE.md as the primary with others as supplementary.

Analyze the results:

1. Issue inventory: Count and categorize all diagnostics (vague, conflict, redundant, ordering, placement, emphasis, linter-job, metadata)
2. Token budget: Note token count and context window percentage
3. Quick wins: Identify the highest-impact, lowest-effort improvements

Phases 2–5 are REQUIRED

These phases are mandatory regardless of MCP tool availability. If a tool fails, perform manual analysis for that phase. A report that skips entire phases due to tool unavailability is not acceptable — perform the manual fallback instead.

alignkit lint diagnostics (VAGUE, CONFLICT, etc.) use regex-based heuristics and may produce false positives. For any rule flagged VAGUE, re-read it in context before downgrading — a rule saying "Consider using TypeScript" may be contextually specific despite matching the VAGUE pattern. Do not blindly convert lint diagnostics into effectiveness ratings.

Phase 3: Effectiveness Analysis

Using the project context from the lint results (dependencies, tsconfig, directory tree), rate each rule's effectiveness:

• HIGH: Concrete, actionable, relevant to this project's stack
• MEDIUM: Reasonable but generic or missing project-specific details
• LOW: Vague, references absent tools, or states what Claude already knows

For any rule rated MEDIUM or LOW, manually re-read the rule and verify your assessment against the actual codebase — is it truly irrelevant, or did the heuristics miss project-specific context?

Phase 4: Adherence Analysis

Call alignkit_local_check first for conformance data. Then call alignkit_check for session history adherence data (if available). Analyze:

1. Overall adherence: What percentage of rules are being followed?
2. Problem rules: Which rules have consistently low adherence?
3. Unresolved rules: Evaluate unresolved rules against session action evidence
4. Trend: Is adherence improving or declining?

For any rule marked "violates", manually verify by reading the relevant code — spot-check 2-3 files to confirm the violation is real. For "unverifiable" verdicts, try alternate verification (Glob, Grep) before accepting.

If no session history exists, note this limitation but still complete conformance analysis using alignkit_local_check. Do NOT skip Phase 4 entirely.

Phase 5: Convention Discovery

Follow the methodology in the /discover skill (skills/discover/SKILL.md):

• Sample 8-12 source files across the project's major directories
• Identify consistent patterns (import styles, naming, error handling, architecture)
• Apply value filtering: only include conventions where violation would cause real problems
• Use 90%+ consistency as the threshold for strong conventions, 70-89% for likely conventions
• Reference skills/discover/references/convention-categories.md for the full category list

Aim for 8-12 high/medium-value conventions. Fewer, stronger rules beat comprehensive lists.

Phase 6: Report

Produce a structured report combining all findings:

# Instruction Review — {project name}

## Summary

{2-3 sentence executive summary: overall quality, key findings, health assessment}

## Quality Score

- **Rules**: {n} rules across {n} files · {tokens} tokens ({%} of context)
- **Issues**: {n} issues found ({n} errors, {n} warnings)
- **Adherence**: {%} across {n} sessions ({trend})

## Priority Fixes

{Top 3-5 most impactful changes, ordered by priority. Each should be specific and
actionable with the exact change to make.}

## Detailed Findings

### Quality Issues
{Issues grouped by type with specific rules cited}

### Effectiveness
{MEDIUM and LOW rules with suggested rewrites or REMOVE recommendations}

### Adherence Problems
{Rules with low adherence and analysis of why}

### Discovered Conventions
{Conventions found in the code but not documented as rules — with evidence and suggested rules}

### Consolidation Opportunities
{Rules that can merge, with merged text and token savings}

## Recommendations

{3-5 strategic recommendations beyond individual fixes. Examples:
- "Consider converting your 4 test-related rules into a single hook"
- "Your instruction file is 180% of the recommended token budget — prioritize consolidation"
- "3 rules reference Jest but your project uses Vitest — update or remove"}

Guidelines

• If an MCP tool fails, perform manual analysis for that phase (see Phase 2 manual steps). Do not skip the phase. In the report, note which phases used MCP vs. manual analysis. If no instruction files exist at all, say so directly — that IS the finding.
• Be thorough but concise — this is a professional audit, not a verbose essay
• Prioritize ruthlessly — put the highest-impact findings first
• Every finding must cite specific rules, files, or evidence
• Recommendations should be concrete and actionable
• If adherence data is unavailable, say so honestly and focus on quality analysis
• The report should be useful even if the user just skims the Summary and Priority Fixes
• Verify by reading, not by executing. Use Read, Grep, and Glob to analyze instruction files and their referenced code. Do NOT write or run ad-hoc scripts (Python, Node, shell one-liners) to parse YAML, count tokens, or test rule patterns — alignkit already does that. Read files and reason about them.