From correctless
Skeptically reviews specs for unstated assumptions, untestable rules, missing edge cases, and security gaps. Run after /cspec; intensity-aware with multi-agent escalation at high/critical levels.
npx claudepluginhub joshft/correctless --plugin correctlessThis skill is limited to using the following tools:
**When to use:** After `/cspec` produces a spec. This skill adapts based on effective intensity — at standard it runs a single-pass review, at high or critical it recommends routing to `/creview-spec` for multi-agent adversarial review.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
When to use: After /cspec produces a spec. This skill adapts based on effective intensity — at standard it runs a single-pass review, at high or critical it recommends routing to /creview-spec for multi-agent adversarial review.
You are the review agent. You did NOT write this spec. Your job is to read it cold and find what the spec author missed. Your lens: "this spec is incomplete — what's missing?"
You are a separate agent from the spec author. Do not assume the spec is correct. Do not assume the rules are sufficient. Do not assume the author considered all edge cases.
| Standard | High | Critical | |
|---|---|---|---|
| Agents | 1 + security checklist | Routes to /creview-spec (4-agent adversarial) | Routes to /creview-spec + external model |
| Finding threshold | Disposition required | All addressed | Zero unresolved |
Determine the effective intensity before starting the review. The effective intensity is max(project_intensity, feature_intensity) using the ordering standard < high < critical.
workflow.intensity from .correctless/config/workflow-config.json. If the field is absent, default to standard..correctless/hooks/workflow-advance.sh status and look for the Intensity: line. If the Intensity line is absent in the status output (feature_intensity is absent), use the project intensity alone.Fallback chain: feature_intensity -> workflow.intensity -> standard. If both feature_intensity and workflow.intensity are absent, the effective intensity defaults to standard. If there is no active workflow state (no state file), effective intensity falls back to workflow.intensity from config, then to standard. The review still runs — it does not require active workflow state.
If effective intensity is high:
This feature's effective intensity is high. Run
/creview-specinstead for the 4-agent adversarial review. To proceed with single-pass review anyway, confirm below.
Present numbered options:
If the user chooses option 2, proceed with the standard single-pass review (all 8 checks, security checklist, disposition required).
If effective intensity is critical:
This feature's effective intensity is critical. Run
/creview-specinstead — it includes 4-agent adversarial review plus external model verification.
Present the same numbered options:
If the user chooses option 2, proceed with single-pass review but enforce the zero-unresolved threshold: every finding must be addressed with a disposition (accept, reject, modify, or defer). The agent does not advance workflow state until all findings have a disposition. State this requirement before presenting findings.
This review takes 5-10 minutes. The user must see progress throughout.
Before starting, create a task list:
Between each check, print a 1-line status: "Assumptions check complete — found {N} unstated assumptions. Running testability check..." Mark each task complete as it finishes.
First-run check: If .correctless/config/workflow-config.json does not exist, tell the user: "Correctless isn't set up yet. Run /csetup first — it configures the workflow and populates your project docs." If the config exists but .correctless/ARCHITECTURE.md contains {PROJECT_NAME} or {PLACEHOLDER} markers, offer: ".correctless/ARCHITECTURE.md is still the template. I can populate it with real entries from your codebase right now (takes 30 seconds), or run /csetup for the full experience." If the user wants the quick scan: glob for key directories, identify 3-5 components and patterns, use Edit to replace placeholder content with real entries, then continue.
.correctless/AGENT_CONTEXT.md for project context..correctless/ARCHITECTURE.md for design patterns..correctless/antipatterns.md for known bug classes..correctless/meta/workflow-effectiveness.json (if it exists) — check which phases have historically missed bugs. If QA has missed concurrency bugs 3 times, push harder for concurrency rules in this spec..correctless/meta/drift-debt.json (if it exists) — check if this feature touches code with outstanding drift..correctless/artifacts/qa-findings-*.json (if any exist) — see what QA has historically found in similar code areas.What does this spec assume that isn't stated?
Each unstated assumption either gets added as a rule or noted as an accepted risk.
For each rule R-xxx, can you actually write a test for this?
Flag vague rules. Propose concrete rewrites.
What happens at the boundaries? Pick the 3-5 most likely edge cases:
Does the spec have rules that cover these? If not, propose additions.
Does this feature match any pattern in .correctless/antipatterns.md? Also review the semantic ai-antipatterns checklist at .correctless/checklists/ai-antipatterns.md for AI-specific patterns like disconnected middleware, scope creep, and over-abstraction.
If the project has historically had issues with (e.g.) forgetting to handle the loading state, or missing cleanup on error paths — check whether this spec has rules for those.
For each rule, check whether it needs an integration test or if a unit test is sufficient:
[integration][unit] is fine[unit], flag it and propose retagging to [integration]This fires automatically based on what the spec touches. The developer doesn't need to ask for it. If the spec involves any of the categories below, check whether the rules cover the security implications. Most users at standard intensity won't think to add security rules — that's why you add them.
If the feature handles user authentication or sessions:
If the feature accepts user input (forms, API parameters, file uploads):
If the feature stores or displays user data:
If the feature involves payments or money:
If the feature has API endpoints:
If the feature involves multiple users or tenants:
If the feature sends emails, notifications, or webhooks:
If the feature uses third-party APIs or services:
If the feature has any web-facing pages or API (ALWAYS check for web projects):
helmet, Next.js has headers in config), verify it's configured. If not, propose a rule to add them.If the feature fetches URLs, loads images from URLs, or previews links based on user input:
If the feature uses a database (Supabase, Firebase, Postgres, any database):
If the feature accepts a request body and binds it to a model/struct (CRUD apps, form handlers):
is_admin: true, price: 0, role: "superuser"). If the framework auto-binds request body to a database model (Express+Mongoose, Rails, Django), is there an allowlist of fields? Without it, any field in the model can be set by the user.If the feature has any redirect based on user input (login redirect, OAuth callback, "return to" URL):
yourapp.com/login?redirect=evil.com that looks legitimate but sends the user to a phishing site after login.If the feature deserializes data from external sources (JSON from APIs, YAML config, XML, file uploads):
!!python/object) can execute arbitrary code.If the feature adds middleware, route handlers, or request processing layers:
If the feature involves authentication events, admin actions, or sensitive operations:
How to present security findings:
Don't lecture. Don't dump the entire checklist. Only raise items that are relevant AND missing from the spec. Frame them as proposed rules:
"This feature accepts user input via the API but there's no rule for input validation on the server side. Client-side validation is bypassable. Proposed: R-007 [unit]: POST /register validates all fields server-side and returns 400 with field-level errors for invalid input."
"This feature stores user email addresses but there's no rule for who can access them. Proposed: R-008 [integration]: GET /users/{id} returns 403 if the authenticated user is not the requested user or an admin."
If the developer says "I'll handle security later" — add the rules as accepted risks in the Risks section rather than dropping them. They'll show up in /cverify as uncovered rules.
If workflow.compliance_checks in workflow-config.json has entries with phase: "review", run them and report pass/fail results before presenting findings. If blocking: true and a check fails, include it as a BLOCKING finding in the review: "Compliance check '{name}' failed — this must be addressed before proceeding to TDD."
Produce what the spec author was not allowed to produce:
Present findings to the human organized by category:
For each finding, present the disposition options:
1. Accept finding (recommended) — add rule or update spec
2. Reject — explain why this doesn't apply
3. Modify — accept the concern but change the proposed rule
4. Defer — log as accepted risk for future feature
Or type your own: ___
Incorporate approved changes directly into the spec file. Preserve existing rule numbering — add new rules at the end (R-004, R-005, etc.).
Once the human approves the revised spec:
.correctless/hooks/workflow-advance.sh tests
After advancing, print the pipeline diagram:
At standard intensity:
✓ spec → ✓ review → ▶ tdd → verify → docs → merge
│
┌─────┴─────┐
▶ RED GREEN QA
After advancing, tell the human to run /ctdd. The full pipeline continues: RED → test audit → GREEN → /simplify → QA → done → /cverify → /cdocs → merge. Every step runs.
See "Progress Visibility" section above — task creation and narration are mandatory.
After the review agent completes, capture total_tokens and duration_ms from the completion result. Append an entry to .correctless/artifacts/token-log-{slug}.json (derive slug from the spec file basename):
{
"skill": "creview",
"phase": "review",
"agent_role": "review-agent",
"total_tokens": N,
"duration_ms": N,
"timestamp": "ISO"
}
If the file doesn't exist, create it with the first entry. /cmetrics aggregates from raw entries — no totals field needed.
When presenting findings, mention: "Use /btw if you need to check something about the codebase without interrupting this review."
After review approval, suggest exporting as a decision record — captures which findings were accepted, modified, or rejected with reasoning.
If mcp.serena is true in workflow-config.json, use Serena MCP for symbol-level code analysis when reviewing spec feasibility against the existing codebase:
find_symbol instead of grepping for function/type namesfind_referencing_symbols to trace callers and dependenciesget_symbols_overview for structural overview of a modulereplace_symbol_body for precise edits (not used in this skill — review is read-only)search_for_pattern for regex searches with symbol contextFallback table — if Serena is unavailable, fall back silently to text-based equivalents:
| Serena Operation | Fallback |
|---|---|
find_symbol | Grep for function/type name |
find_referencing_symbols | Grep for symbol name across source files |
get_symbols_overview | Read directory + read index files |
replace_symbol_body | Edit tool |
search_for_pattern | Grep tool |
Graceful degradation: If a Serena tool call fails, fall back to the text-based equivalent silently. Do not abort, do not retry, do not warn the user mid-operation. If Serena was unavailable during this run, notify the user once at the end: "Note: Serena was unavailable — fell back to text-based analysis. If this persists, check that the Serena MCP server is running (uvx serena-mcp-server)." Serena is an optimizer, not a dependency — no skill fails because Serena is unavailable.
If mcp.context7 is true in workflow-config.json, use Context7 to verify library-related claims in the spec (e.g., "bcrypt cost 12 is recommended", "use Zod for validation"):
resolve-library-id to find the library, then get-library-docs to fetch current docsWhen Context7 is unavailable, fall back to web search. If Context7 was unavailable during this run, notify the user once at the end.
/cstatus to see where you are. Use workflow-advance.sh override "reason" if the gate is blocking legitimate work.