Consult

/consult — Project Consultant

Interactive project consultant that understands your project and guides improvements through targeted, context-aware questions. Like sitting down with a senior developer who looks at your codebase and asks the right questions.

Problem

Developers know something is off but cannot pinpoint what to improve first. Generic advice ("add tests", "update dependencies") is not helpful without understanding the project's context, constraints, and goals. A good consultant asks before prescribing.

3 Modes

Mode: start

Full interactive consultation. This is the primary mode.

Phase 1 — Understand (Automatic)

Run /scan full internally or read existing .scan-profile.json if recent (< 7 days old).

Decision logic:

IF .scan-profile.json exists AND scanDate < 7 days ago:
  -> Read existing profile, skip scan
  -> Tell user: "Using existing scan from {date}"
IF .scan-profile.json exists AND scanDate >= 7 days ago:
  -> Re-scan, profile is stale
IF .scan-profile.json does not exist:
  -> Run /scan full internally

After scan, compile an internal understanding of the project:

• What is this project? (type, purpose, architecture)
• What stack does it use?
• What is present? (tests, CI, docs, deployment)
• What is missing? (gaps from quality indicators)
• What is the apparent maturity level? (prototype, MVP, production, legacy)

Phase 2 — Ask (Interactive)

Ask targeted questions based on scan findings. Questions are conditional — only ask what is relevant. Use AskUserQuestion for each question.

Rules for questions:

• Max 5-8 questions per consultation (respect user's time)
• Always offer a recommended answer as first option
• Questions must be specific to what was found, never generic
• Group related questions when possible
• Skip questions where the answer is obvious from the scan

Question Framework

Questions are organized by category. Only ask questions from categories where the scan found gaps or ambiguity.

Category: Project Goals

Always ask (exactly one question to start):

What is the main thing you want to improve about this project?

1. Performance (speed, resource usage)
2. Developer Experience (easier to work with, better tooling)
3. User Experience (design, usability, accessibility)
4. Reliability (fewer bugs, better error handling, monitoring)
5. Security (hardening, auth, data protection)
6. Architecture (structure, scalability, maintainability)
7. Everything — give me a full assessment

Category: Testing (only if scan found gaps)

Category: Dependencies (only if scan found gaps)

Category: CI/CD (only if scan found gaps)

Category: Code Quality (only if scan found gaps)

Category: Documentation (only if scan found gaps)

Category: Deployment & Operations (only if scan found gaps)

Category: Architecture (only if scan found ambiguity)

Category: Constraints

Always ask (exactly one question to close):

What are the constraints for improvements?

1. Quick fixes only — I need results today (30 minutes)
2. A focused afternoon — I can invest 2-4 hours
3. Proper refactor — I have a few days
4. Full rebuild is on the table — whatever it takes

Who maintains this project?

1. Just me (solo developer)
2. Small team (2-5 people)
3. Larger team or open source

Phase 3 — Recommend (Automatic)

Based on scan results + user answers, generate a prioritized recommendation list.

Priority tiers:

Recommendation generation rules:

• Quick Wins first — always give the user something they can do right now
• Match recommendations to the user's stated time constraint
• If user said "quick fixes only", only show Tier 1 items
• If user said "full rebuild", include Tier 3 items
• Never recommend changing something that is working well
• Respect the user's stack preference (if they said "optimize current", no stack changes)
• Include reasoning for every recommendation — "why" matters

Phase 4 — Plan (Automatic)

Generate the consultation report and structured plan.

Mode: quick

Automated recommendations without deep questions. For when you want fast answers.

Procedure

1. Run /scan full internally (or read existing profile)
2. Skip Phase 2 (no interactive questions)
3. Assume defaults:
   • Goal: "Everything — full assessment"
   • Constraints: "Focused afternoon (2-4 hours)"
   • Maintainer: "Solo developer"
4. Generate recommendations (Phase 3) based on scan gaps alone
5. Output compact report

Output Format (quick mode)

Quick Consultation: {project-name}
============================================

Based on scan, here are the top improvements:

QUICK WINS (do these now):
  1. [+CLAUDE.md] Generate a CLAUDE.md — run /scan generate
  2. [+Linting] Add Biome for formatting/linting consistency
  3. [+.editorconfig] Add .editorconfig for cross-editor consistency

RECOMMENDED (invest an afternoon):
  4. [+Tests] Add Vitest for critical business logic
  5. [+CI] Set up GitHub Actions: test + lint + build on PR
  6. [+Deps] Add Dependabot for automated dependency updates

STRATEGIC (plan when ready):
  7. [TypeScript] Migrate from JavaScript to TypeScript
  8. [Docker] Add containerization for deployment consistency

Run /consult start for a guided consultation with targeted questions.

Mode: plan

Re-generate or refine the plan from a previous consultation.

Procedure

1. Read .consult-state.json
   • If not found: Tell user to run /consult start first
2. Re-generate plan based on stored answers and current scan
3. Optionally re-scan if profile is stale (> 7 days)
4. Output the plan (same format as start mode Phase 4)

Useful when: The user ran /consult start previously, made some improvements, and wants an updated plan based on current state.

Consultation Report Format

Generated at the end of start and quick modes.

Project Consultation: {project-name}
Date: {date}
============================================

PROJECT UNDERSTANDING:
  Type: {architecture} ({framework})
  Stack: {language} + {framework} + {css} + {database}
  Maturity: {prototype | mvp | production | legacy}
  Maintainer: {solo | small-team | large-team}

HEALTH ASSESSMENT:
  Overall: {score}/10
  +-----------------+-------+----------------------------------+
  | Category        | Score | Assessment                       |
  +-----------------+-------+----------------------------------+
  | Stack           |  9/10 | Modern, well-chosen              |
  | Testing         |  3/10 | No tests, significant risk       |
  | CI/CD           |  7/10 | CI exists, deploy is manual      |
  | Documentation   |  4/10 | README only, no CLAUDE.md        |
  | Code Quality    |  8/10 | TypeScript strict, linting good  |
  | Security        |  6/10 | Basics covered, no dep scanning  |
  | Deployment      |  5/10 | Docker exists, no health checks  |
  +-----------------+-------+----------------------------------+

USER PRIORITIES:
  Primary goal: {from question 1}
  Time budget: {from constraints question}
  Stack changes: {open to changes | optimize current}

IMPROVEMENT PLAN:

Phase 1 — Quick Wins (Today, ~1 hour total)
  1. Generate CLAUDE.md
     Why: Helps AI tools and new contributors understand the project
     How: Run /scan generate
     Effort: 2 minutes

  2. Add .editorconfig
     Why: Consistent formatting across editors and contributors
     How: Create .editorconfig with indent, charset, EOL rules
     Effort: 5 minutes

  3. Add Dependabot configuration
     Why: Automated security updates for dependencies
     How: Create .github/dependabot.yml
     Effort: 10 minutes

Phase 2 — Medium Effort (This week, ~4 hours total)
  4. Set up Vitest for critical paths
     Why: {user said reliability is important} + no tests exist
     How: Install vitest, create test for {most critical module}
     Effort: 2 hours
     Dependencies: None

  5. Add health checks to Docker setup
     Why: Production containers should self-report health
     How: Add HEALTHCHECK to Dockerfile, health endpoint to app
     Effort: 1 hour
     Dependencies: None

Phase 3 — Strategic (Plan for next sprint)
  6. Migrate to TypeScript strict mode
     Why: Catches bugs at compile time, better DX
     How: Enable strict in tsconfig, fix type errors incrementally
     Effort: 2-5 days (depending on codebase size)
     Dependencies: Items 4-5 should be done first

NEXT STEPS:
  - Start with Phase 1 items — they take minutes and have immediate impact
  - Run /project-audit for a thorough code-level review
  - After implementing changes, run /consult plan to get an updated plan

State File (.consult-state.json)

Written after every consultation. Enables /consult plan to regenerate.

{
  "version": "1.0",
  "consultDate": "2026-03-20",
  "mode": "start",
  "project": "my-project",
  "scanProfile": ".scan-profile.json",
  "answers": {
    "primaryGoal": "reliability",
    "timeBudget": "afternoon",
    "maintainer": "solo",
    "testing": "add-unit-tests",
    "cicd": "keep-current",
    "typescript": "not-now",
    "docker": "add-health-checks",
    "claudeMd": "yes-generate"
  },
  "recommendations": [
    {
      "id": 1,
      "tier": "quick-win",
      "title": "Generate CLAUDE.md",
      "status": "open",
      "effort": "2 minutes"
    },
    {
      "id": 2,
      "tier": "medium",
      "title": "Set up Vitest",
      "status": "open",
      "effort": "2 hours"
    }
  ],
  "healthScore": {
    "overall": 6,
    "categories": {
      "stack": 9,
      "testing": 3,
      "cicd": 7,
      "documentation": 4,
      "codeQuality": 8,
      "security": 6,
      "deployment": 5
    }
  }
}

Maturity Assessment

Automatically determined from scan results. Guides the tone of recommendations.

Detection heuristics:

prototype:  sourceFiles < 20 AND no tests AND no CI
mvp:        sourceFiles < 100 AND (no tests OR no CI)
production: tests AND CI AND deployment config
legacy:     framework version > 2 majors behind OR node < current LTS - 2

Question Quality Rules

Questions make or break the consultation. These rules ensure they are valuable.

1. Context-aware — Every question references a specific finding from the scan
2. Actionable options — Each answer maps to a concrete recommendation
3. Opinionated defaults — Always mark the recommended option (first position)
4. No dead-end answers — "Not now" is valid but still generates alternative advice
5. Progressive depth — Start broad (goals), narrow down (specifics), close with constraints
6. No repetition — If the scan already answered it, do not ask
7. Grouped when related — "Tests + CI" can be one compound question if both are missing
8. Max 8 questions — Hard limit. Prioritize questions by impact of the answer

Integration with Other Skills

Depends On

Recommends After

State Contract

Anti-Patterns (What NOT to Do)

Context Protection

• Max 10 questions per consultation session (hard limit)
• Max 15 recommendations in the plan
• Write state after Phase 2 (answers preserved even if session ends)
• Write state after Phase 4 (full plan preserved)
• On context limit: Save state, recommend /consult plan in next session

Rules

1. Scan before consulting — Never recommend without understanding the project first
2. Ask before prescribing — Phase 2 exists for a reason. Do not skip it in start mode
3. Respect user answers — If they said "not now" to TypeScript, do not sneak it into the plan
4. Concrete over abstract — Every recommendation must have a "How" with specific steps
5. Effort estimates are honest — Do not underestimate. Include setup time
6. No stack shaming — Every stack was chosen for a reason. Improve, do not judge
7. Quick wins are real — Tier 1 items must genuinely take under 30 minutes
8. Plans are actionable — Someone should be able to follow the plan step by step
9. State enables continuity — A consultation can span multiple sessions via state
10. Read-only by default — The consultant does not modify files. It creates a plan. Execution is separate

Files

consult/
└── SKILL.md    <- This file