benjaminshoemaker/vision-audit

Vision Audit

A comprehensive audit that evaluates the toolkit against its vision, compares to SDLC outcomes, researches the landscape, and generates feature proposals with rationale.

This is both an audit tool and a roadmap generator.

Key principle: Focus on outcomes, not practices or tools. Proposals should achieve outcomes in ways that align with our principles and differentiate from competitors.

Scope

This skill is toolkit-specific. It reads the toolkit's direction documents and generates proposals for improvement. Not synced to target projects.

Trigger

Manual only. Run /vision-audit when you want to:

• Check alignment with vision and SDLC outcomes
• Get researched feature proposals
• Understand competitive positioning

---

Prerequisites

The following documents should exist in the repository root:

| Document | Purpose | Required? | |----------|---------|-----------| | VISION.md | Principles, scope, success criteria | Yes | | SDLC_REFERENCE.md | Outcomes to achieve | Yes | | COMPETITORS.md | Landscape analysis, differentiation | Recommended |

If COMPETITORS.md is missing, proposals will lack competitive context but audit will still run.

---

Workflow

Copy this checklist and track progress:

Vision Audit Progress:
- [ ] Phase 1: Parse direction documents
- [ ] Phase 2: Gather evidence from codebase
- [ ] Phase 3: Evaluate vision alignment (R/Y/G scoring)
- [ ] Phase 4: Classify SDLC outcomes (ACHIEVED / AVOIDED / OPPORTUNITY)
- [ ] Phase 5: Research opportunities (web search + competitor check)
- [ ] Phase 6: Generate proposals with rationale
- [ ] Phase 7: Output combined report

---

Part A: Vision Alignment Audit

Phase 1: Parse Direction Documents

Read and extract from each document:

VISION.md: | Section | Extract | |---------|---------| | Problem | Context (not scored) | | Aspiration | Core goal | | Principles | Numbered principles (priority order) | | AI Strengths | What to leverage | | AI Weaknesses | What to guard against | | Scope In/Out | Boundaries for classification | | Success | Measurable criteria |

SDLC_REFERENCE.md:

• All outcomes by phase (1.1, 1.2, 2.1, etc.)
• "Why it matters" for each

COMPETITORS.md:

• Competitor list and philosophies
• Feature matrix (what they have vs us)
• Strengths to learn from
• Our unique differentiation
• Gaps & opportunities already identified

Phase 2: Gather Evidence

Scan the codebase:

| Source | What to Look For | |--------|------------------| | .claude/skills/ | Skill count, complexity, patterns | | .claude/commands/ | Legacy commands | | README.md | Feature claims, workflow | | AGENTS.md | Workflow rules | | docs/ | Documentation coverage | | Prompt files | Spec/plan generation patterns |

Phase 3: Evaluate Vision Alignment

Score each vision item:

| Score | Meaning | |-------|---------| | 🟢 Green | Aligned — clear evidence | | 🟡 Yellow | Partial — mixed signals | | 🔴 Red | Misaligned — contradiction |

---

Part B: SDLC Gap Analysis

Phase 4: Classify SDLC Outcomes

For each outcome in SDLC_REFERENCE.md:

ACHIEVED     → Toolkit achieves this outcome
AVOIDED      → Out of scope per VISION.md (with citation)
OPPORTUNITY  → In scope but not yet achieved

Decision Tree:

Does toolkit achieve this outcome?
├─ YES → ACHIEVED
├─ NO → Is it out of scope per VISION.md?
│       ├─ YES → AVOIDED (cite the scope exclusion)
│       └─ NO → OPPORTUNITY (proceed to research)

---

Part C: Research & Proposals (NEW)

Phase 5: Research Opportunities

For each OPPORTUNITY identified, conduct research:

5a. Web Research (Live)

Use WebSearch to find current information:

Search: "{outcome} best practices 2026"
Search: "AI coding tools {outcome}"
Search: "{specific capability} implementation patterns"

Extract:

• Current industry trends
• How leading tools approach this
• Emerging patterns or technologies

5b. Competitor Analysis

Check COMPETITORS.md for each opportunity:

• Do any competitors address this? How?
• What works well in their approach?
• What can we do differently/better?
• Does addressing this strengthen our differentiation?

5c. Principles Filter

For each opportunity, check against VISION.md principles:

□ Simplicity: Does this add too much complexity?
□ Flexibility: Does this force a workflow?
□ 90% Rule: Do most solo developers want this?

If an opportunity fails the principles filter, mark it as SKIP with reasoning.

Phase 6: Generate Proposals

For each researched opportunity that passes the principles filter, generate a proposal:

════════════════════════════════════════════════════════════════════

PROPOSAL: {Short Title}
─────────────────────────

Outcome Addressed: {SDLC outcome ID and name}

Gap: {What's missing today}

Research Findings:
  • Trend: {What current best practices say}
  • Competitors: {How others handle this}
  • Differentiation: {How we can do it uniquely}

Proposal: {What to build/change}

Rationale:
  • Vision fit: {How this advances our aspiration}
  • Principle alignment: {Which principles it respects}
  • Competitive angle: {Why our approach is better}

Implementation Sketch:
  • Approach: {High-level how}
  • Files affected: {Which skills/prompts to modify}
  • Effort: LOW / MEDIUM / HIGH

Priority: HIGH / MEDIUM / LOW
  {Brief justification for priority}

════════════════════════════════════════════════════════════════════

---

Phase 7: Combined Report Structure

╔══════════════════════════════════════════════════════════════════╗
║                       VISION ALIGNMENT AUDIT                      ║
╚══════════════════════════════════════════════════════════════════╝

SUMMARY
───────
Vision Alignment:  X of Y items (🟢 N / 🟡 N / 🔴 N)
SDLC Outcomes:     X achieved, Y avoided, Z opportunities
Proposals:         N proposals generated (H high, M medium, L low)

════════════════════════════════════════════════════════════════════

PART A: VISION ALIGNMENT
────────────────────────
[R/Y/G scoring for aspiration, principles, AI strengths/weaknesses,
scope, success criteria]

════════════════════════════════════════════════════════════════════

PART B: SDLC OUTCOME COVERAGE
─────────────────────────────
[By-phase listing of ACHIEVED / AVOIDED / OPPORTUNITY]

[Coverage summary table]

════════════════════════════════════════════════════════════════════

PART C: PROPOSALS
─────────────────

[For each proposal, full detail as shown in Phase 6]

════════════════════════════════════════════════════════════════════

SKIPPED OPPORTUNITIES
─────────────────────
[Opportunities that failed principles filter, with reasoning]

════════════════════════════════════════════════════════════════════

COMPETITIVE POSITIONING
───────────────────────
Summary of how proposals strengthen differentiation:
• {Proposal 1} reinforces {unique angle}
• {Proposal 2} addresses gap vs {competitor}
• etc.

════════════════════════════════════════════════════════════════════

RECOMMENDED ROADMAP
───────────────────
Based on this audit, suggested implementation order:

1. {HIGH priority proposal} - {one-line rationale}
2. {HIGH priority proposal} - {one-line rationale}
3. {MEDIUM priority proposal} - {one-line rationale}
...

---

Research Guidelines

What to Search For

| Opportunity Type | Search Queries | |-----------------|----------------| | Security | "shift-left security AI coding 2026", "SAST tools modern development" | | Testing | "AI-assisted testing best practices", "test generation tools 2026" | | Context management | "LLM context management techniques", "AI coding context rot solutions" | | Workflow | "AI coding workflow automation", "spec-driven development tools" |

Competitive Questions to Answer

For each opportunity, answer:

1. Which competitors address this? (check COMPETITORS.md feature matrix)
2. What's their approach? (philosophy, not just features)
3. What works well? What doesn't?
4. Can we achieve the outcome with less complexity?
5. Can we leverage our unique angles (verification-first, cross-model, simplicity)?

Principles Filter Details

Simplicity over capability:

• Would this add a new skill? (caution)
• Would this add significant lines to existing skills? (caution)
• Could this be documentation instead of tooling? (prefer docs)

Flexibility over guardrails:

• Does this force users into a specific workflow?
• Can users opt-out or skip this?
• Is this additive rather than mandatory?

90% rule:

• Is this a common need for solo developers?
• Is this enterprise/team-specific? (skip)
• Is this niche technology-specific? (skip)

---

Edge Cases

COMPETITORS.md Missing

NOTE: COMPETITORS.md not found.

Proposals will be generated without competitive analysis.
Consider creating COMPETITORS.md for richer proposals.

No Opportunities Found

All SDLC outcomes are either ACHIEVED or correctly AVOIDED.

No proposals generated. The toolkit is well-aligned with its vision
and SDLC best practices.

Consider:
- Reviewing COMPETITORS.md for differentiation opportunities
- Checking if new SDLC trends have emerged (run with fresh research)

Too Many Opportunities

If more than 10 opportunities are identified:

• Prioritize ruthlessly using principles filter
• Generate full proposals only for HIGH priority items
• Summarize MEDIUM/LOW in a list without full research

Research Rate Limits

If web search is rate-limited:

• Fall back to COMPETITORS.md analysis only
• Note that proposals lack current trend research
• Suggest re-running later for full analysis

---

Error Handling

| Situation | Action | |-----------|--------| | VISION.md is missing | Stop and report "VISION.md not found — cannot run vision audit"; do not proceed | | SDLC_REFERENCE.md is missing | Stop and report "SDLC_REFERENCE.md not found — cannot evaluate outcomes"; do not proceed | | COMPETITORS.md is missing | Continue without competitive analysis; note in report that proposals lack competitive context | | Web search is rate-limited or unavailable | Fall back to COMPETITORS.md analysis only; note that proposals lack current trend research | | More than 10 OPPORTUNITY items identified | Generate full proposals only for HIGH priority items; summarize MEDIUM/LOW in a compact list |

Review Your Output

After generating proposals, verify:

• Each proposal was cross-checked against the design principles filter
• No SDLC outcomes from VISION.md were missed
• Proposals are actionable and scoped (not vague aspirations)

Output Principles

1. Actionable — Each proposal should be implementable
2. Justified — Every recommendation tied to vision/outcomes/competition
3. Honest — If something doesn't fit our principles, say so and skip it
4. Prioritized — Don't overwhelm; rank by impact and effort
5. Differentiated — Proposals should strengthen our unique positioning