ai

Use when you have a spec or PRD that needs decomposing into small, verifiable implementation tasks. Use before any build cycle to ensure tasks are thin vertical slices with clear acceptance criteria.

Use when starting a new feature, when requirements are unclear, when asked to write code without a clear spec, or before any non-trivial implementation. Do NOT use for trivial bug fixes or one-line changes.

Use when reviewing codebase architecture for refactoring opportunities, surfacing shallow modules, or proposing deepening refactors. Identifies architectural friction and produces GitHub issues with the ops-triage labeling scheme. Supports interactive (human approval) and auto (CI/headless) modes — auto mode files every surviving candidate directly and writes a step-summary report.

Use when reviewing a pull request or code change before merge. Use for the five-axis evaluation (correctness, readability, architecture, security, performance), exposure × impact severity classification, AC coverage verification, and the `## Automated review` comment. Use in both human and CI mode — the methodology is identical; only the inputs and agent invocation differ.

Use when working in a Next.js 15 App Router project — editing app/, src/app/, components/, server actions, or route handlers. Enforces project conventions for queries, mutations, and data fetching.

Use when editing *.ts or *.tsx files in this project. Enforces TypeScript conventions including Zod-derived types, Prisma type patterns, type-only imports, and shared constant extraction.

Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyse network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured.

Use when code feels over-engineered, before refactoring, or as a cleanup step after implementation. Use when asked to simplify, reduce complexity, or make code clearer. Do NOT use for performance optimization, feature work, or architecture redesign.

Use when running the autonomous content pipeline — scanning a content queue, ingesting sources, evaluating readiness, writing articles, running quality passes, and publishing via PRs. Also handles self-learning from reviewer feedback and periodic content pruning. Requires a project writing style guide at docs/writing-style-guide.md.

Use when starting work in an unfamiliar codebase, when the agent lacks project context, when loading into a new session, or before making architectural decisions. Ensures the agent has the right context at the right time without overloading.

Use when tests fail, builds break, or behaviour doesn't match expectations. Use when you need a systematic approach to finding root cause instead of guessing.

Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when deciding whether to maintain or sunset existing code.

Use when making significant architectural decisions, changing public APIs, or shipping features where future engineers and agents will need context to understand why things are built the way they are.

Use when correctness matters more than speed, when working in unfamiliar code, when stakes are high (production, security-sensitive logic, irreversible operations), or any time a confident output would be cheaper to verify now than to debug later. Runs a CLAIM → EXTRACT → DOUBT → RECONCILE loop to adversarially challenge assumptions before committing.

Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing state, or when the output needs to look and feel production-quality rather than AI-generated.

Use when making any code change. Use when committing, branching, resolving conflicts, setting up worktrees for parallel agent work, or when you need to organise work across multiple parallel streams.

Use when implementing any planned task, building a feature slice-by-slice, or working through a GitHub issue. Always use with test-driven-development and quality-gate. Do NOT use for research, exploration, or spike work.

Use when an ask is underspecified — missing who it's for, why now, or what success looks like. Use when the user explicitly says "interview me", "grill me", or "are we sure?". Use when you catch yourself silently filling in ambiguous requirements before any plan, spec, or code exists.

Use when ending a session, when the user asks to save lessons, or when you notice a correction or preference worth remembering. Captures non-obvious lessons to AGENTS.md or skill files so the agent gets smarter over time. Do NOT use for trivial facts derivable from reading code.

Use when shipping any feature that runs in production. Use when adding logging, metrics, tracing, or alerting. Use when production issues are reported but you can't tell what happened from the available data.

Use when performance requirements exist in a spec, when Core Web Vitals scores are below thresholds, when profiling reveals bottlenecks, or when users or monitoring report slow behaviour. Do not use before measuring — optimisation without data is guessing.

Use when you need lint, typecheck, test, and build to pass before pushing, opening a PR, or merging. Also use when asked to run "checks", "quality gate", or "make sure everything is clean" before submission.

Use when handling user input, authentication, data storage, or external integrations. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services.

Use when preparing to ship a feature, release, or deployment. Use before merging to main, creating a release, or deploying to production. Do NOT use for CI-only changes or internal refactors that don't reach production.

Use when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters. Detects the stack from dependency files, fetches official documentation, implements following documented patterns, and cites sources for every framework-specific decision.

Use when designing, building, documenting, or maintaining RESTful APIs, defining type contracts between modules, or establishing boundaries between frontend and backend. Enforces the project's style guide, response envelopes, pagination, field naming, and release readiness.

Use when building or modifying Laravel applications, including routes, controllers, models, migrations, jobs, actions, and API resources.

Use when writing or fixing PHP code, implementing classes, traits, or interfaces, applying PSR standards, or working with PHP 8.3+ patterns like readonly properties, enums, named arguments, match expressions, and union types.

Use when implementing any logic, fixing any bug, or changing any behaviour. Use when you need to prove code works, when a bug report arrives, or when modifying existing functionality. Do NOT use for config changes, data migrations, or dependency updates.

Use when editing or reviewing text to make it sound more natural and human-written. Removes signs of AI-generated writing based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases.

Use when starting a new SaaS project, scaffolding /docs/ for an agentic codebase, or restructuring existing docs to be agent-readable. Generates a complete /docs/ tree plus a triggered AGENTS.md reference index, by walking the user through a structured quiz.