Claudefiles

Use when the user says: "how does X work", "walk me through", "explain this subsystem", "explain how", "trace the flow". Complexity-adaptive subsystem explanation — builds mental models conversationally, not documentation artifacts.

Use when the user says: "why is this code like this", "why does this exist", "why was this built this way", "decision rationale", "what's the history behind". Decision archaeology — reconstructs historical rationale from evidence, not speculation.

Use when the user says: "comb this", "fine-toothed comb", "comb this brief", "comb this design", "go over this with a fine-toothed comb", "comb the implementation against the design", "check this for consistency", "is this design consistent and complete". Open-ended holistic review of an artifact (or an artifact against a reference) — catches inconsistency, inaccuracy, drift, and thinness a checklist can't. The one-off form of the comb baked into mine-define, mine-plan, and mine-sketch.

Use when the user says: "draft a plan", "create work packages", "generate WPs", "review this plan", or "check the plan". Turns a design doc into task files and validates them against a traceability-focused checklist.

Use when the user says: "ship it" or "commit push and PR". Commits, pushes, and creates a PR in one step.

Use when the user says: "write in beats", "beat by beat", "choose your own adventure writing", "journey-style article", or wants to assemble an article as a series of beats the user picks between.

Use when the user says: "build this", "implement this", "make this change", or "start a feature". Smart entry point that routes to direct implementation or the full caliper v2 workflow based on complexity.

Use when encountering any bug, test failure, or unexpected behavior

Use when the user says: "grill me on this", "poke holes in my idea", "help me think this through", "what am I not thinking about", or wants multi-angle questioning before committing to building something. Pre-pipeline exploration that sharpens thinking.

Use when the user says: "shape this article", "write paragraph by paragraph", "shape this writing", "structure this material", or has raw material ready to shape into a finished article.

Use when the user says: "teach me", "help me learn a new topic", "lesson on", "tutorial on", or wants structured learning over multiple sessions. Not for explaining code in the current repo — that's mine-how or mine-document.

Use when the user says: "spec this out", "help me define what I want to build", "interview me about this idea", "design this change", "write a design doc", or needs to define WHAT and HOW to build something. Proportional discovery interview + codebase investigation → design.md.

Use when the user says: "mockup this UI", "show me what it looks like", "HTML mockup", "UI preview", or "generate a mockup". Generate self-contained HTML mockup files. Reads design/context.md if present for consistent styling.

Use when the user says: "review my changes", "run the reviewers", "code and integration review", "readability review", "maintainability review", "sniff test this", "WTF check", "code smells", "is this code any good", "fresh eyes on this branch", "review this directory", "check this module", "review this skill", "review these instructions". Dispatches three parallel reviewers — code, integration, and a readability pass for code; consistency, instruction quality, and writing quality for instruction files — and consolidates findings into one prioritized report.

Use when the user says: "sketch this out", "sketch this feature", "lightweight plan", "quick design and tasks", or wants structured planning without full caliper ceremony. Produces a lightweight design.md + task files for mine-orchestrate.

Use when the user says: "what would a v2 look like", "how would we rebuild this", "next iteration of this design", "what improvements are we skipping", "what would a mature version look like", "what are we not considering here", "how would we make this more robust", "sophistication ceiling", "elevate this subsystem". Surfaces upward improvements to an existing subsystem through three generator lenses — each candidate annotated with cost and the case against, ordered by signal. A counterweight to solo-dev myopia: it proposes, it never decides.

Use when the user says: "create product context", "generate product.md", "set up product context", "document this product", or "update product context". Generates or refreshes a product.md for the current repo via inference + interview.

Use when the user says: "write this up", "write up for my boss", "summarize this for leadership", "executive summary", "distill this research", "write a summary for leadership", or needs to turn technical research into a readable document for a specific audience.

Use when the user says: "document how X works", "write up how this works", "durable explanation", "explain this for the docs", "document this subsystem". Writes a durable, architectural-altitude explanation that survives code churn.

Use when the user says: "humanize this", "unslop this", "de-slop this", "fix AI writing", "remove AI tells", "clean up AI prose". Edits prose to remove AI writing patterns and add human voice. Analyzes first, then asks how to fix. Prose complement to mine-clean-code.

Use when the user says: "research adding X", "feasibility study", "evaluate approach", or wants a focused investigation before committing. Dispatches the researcher agent for codebase investigation and presents a structured brief.

Use when the user says: "simplify this codebase", "find simplification opportunities", "where can I simplify", "code judo this", "judo this module", "find structural simplifications", "what can I collapse", "reduce complexity in this code". Runs the code-judo posture against existing code (a file, directory, or whole repo) — not a diff — fanning out parallel structural-simplification reviewers and consolidating their moves into one impact-ranked report.

Use when the user says: "challenge this", "poke holes in this", or "what's wrong with this approach". Adversarial review with triage-driven critic selection, parallel critics (1–3 on first run; max 2 on re-challenges). Assumes the target is wrong, finds out why, and argues for a better approach.

Use when the user says: "create PR" or "open pull request". Reviews branch changes and creates a PR on GitHub or Azure DevOps.

Use when the user says: 'decompose this', 'find decomposition opportunities', 'what should I split', 'break this apart', 'this file is too big', 'split opportunities', 'extract candidates', 'find god classes'. Analyzes code for decomposition opportunities — prioritized by Git behavioral signals and structural metrics, with concrete split suggestions.

Use when the user says: "evaluate this repo", "should I use this library", or wants to assess a third-party dependency. Checks test coverage, code quality, maintenance health, bus factor, and maturity.

Use when the user says: "mine fragments", "explore writing", "raw material", "capture fragments", "start writing an article", "gather raw material for an article", or wants to mine raw ideas before committing to structure.

Use when the user says: "prior art", "how do others do this", "what patterns exist", "industry standards for X", or wants to survey external approaches.

Use when the user says: "review this PR", "review PR <number>", "review someone else's PR", "review the PR for <branch>", "review their branch". Reviews another developer's open PR read-only — dispatches the standard reviewer trio, verifies findings against the current PR head, the real code, the PR description, and existing threads before presenting them, and optionally posts them as PR comment threads. Never edits code.

Use when the user says: "find tool gaps", "session archaeology", or "missing cli features". Mines session history for recurring patterns that should be scripts or CLI tools.

Use when the user says: "visual QA", "screenshot review", "review the UI visually", "take screenshots and find issues", or "UX review". Screenshots a live app via Playwright, then analysis agents review the captures — first impressions, cross-page consistency, and unstructured design narrative.

Use when the user says: "wayfinder", "chart this effort", "too big for one session", "multi-session plan", "foggy effort", "progressive discovery", or has a large uncertain effort that needs progressive discovery before planning.

Use when the user says: "clean code check", "style review", "LLM smell check", "code hygiene", "nitpick this", "style check", "find style sins", "nitpicker review", "anal retentive review", "exhaustive style review", "no-filter style report". Dispatches three parallel stylistic checkers — llm-checker (training-bias patterns), lazy-checker (deferred debt), and nitpicker (style hygiene) — and consolidates findings into a report organized by checker with a Summary section for orchestration consumption.

Use when the user says: "commit and push". Commits and pushes changes to the current branch.

Use when the user says: "execute the plan", "orchestrate implementation", or "start executing". Runs tasks task-by-task with implementer + reviewer subagent loop.

Use when the user says: "create a skill", "write a skill", "new skill", or wants to author a new SKILL.md. Guided skill creation following Claudefiles conventions.

Use when the user says: 'create an issue', 'file an issue', 'open an issue', 'write an issue', 'new issue for this'. Codebase-aware issue creation — investigates the code to produce well-structured issues with acceptance criteria, affected areas, and enough detail for automated triage.

Use when the user says: "domain model", "glossary", "sharpen terminology", "define this term", "what does X mean in this codebase", "ubiquitous language", or wants to pin down domain terminology, record an architectural decision, or when another skill needs to maintain the domain model.

Use when the user says: "mutation test", "do my tests actually catch bugs", or wants to verify test quality. Intentionally breaks code to check if tests catch real bugs. No framework needed.

Use when the user says: "address PR comments", "fix review feedback", "fix failing CI", or "resolve merge conflicts". Triages and resolves PR blockers on GitHub or Azure DevOps.

Use when mine-orchestrate Phase 3 runs the post-execution quality gate. Reviews changed files against design doc and task files using a Sonnet subagent.