Spec Critique

Name: Spec Critique
Author: oimiragieo

oimiragieo/agent-studio

44 installs
36 repo stars
Updated July 14, 2026
oimiragieo/agent-studio

Helps with ai & agent building tasks.

About

spec-critique is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.

spec-critique
AI & Agent Building
AI-coding skill

Spec Critique by the numbers

44 all-time installs (skills.sh)
Ranked #7,837 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/oimiragieo/agent-studio --skill spec-critique

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/oimiragieo/agent-studio/spec-critique.svg)](https://skillselion.com/skills/oimiragieo/agent-studio/spec-critique)

Installs	44
repo stars	★ 36
Last updated	July 14, 2026
Repository	oimiragieo/agent-studio ↗

What it does

Helps with ai & agent building tasks.

Files

SKILL.mdMarkdownGitHub ↗

Specification Critique Skill

Overview

Critically review specification documents for accuracy, completeness, and feasibility. Use extended thinking to find issues BEFORE implementation begins.

Core principle: Use extended thinking (deep analysis). Find problems BEFORE implementation.

When to Use

Always:

After spec writing is complete
Before implementation planning begins
When spec involves external integrations
For complex features with multiple components

Exceptions:

Simple specs for trivial changes
Specs already reviewed by another agent

The Iron Law

NO IMPLEMENTATION WITHOUT SPEC CRITIQUE FOR COMPLEX TASKS

Complex tasks (external integrations, multi-service changes) must have spec critique.

Inputs Required

Before critiquing, ensure you have:

1. spec.md - The specification to critique 2. Requirements document - Original user requirements 3. Project context - Tech stack, patterns

Workflow

Phase 1: Load All Context

# Read the spec
cat .claude/context/specs/[task-name]-spec.md

# Read original requirements
cat .claude/context/requirements/[task-name].md

# Read project context
cat .claude/context/tech-stack.md

Understand:

What the spec claims
What the user originally requested
What patterns exist in the codebase

Phase 2: Deep Analysis (USE EXTENDED THINKING)

CRITICAL: Use extended thinking for this phase. Think deeply about:

Technical Accuracy

Compare spec against requirements and codebase:

Package names: Does spec use correct package names?
Import statements: Do imports match API patterns?
API calls: Do function signatures match documentation?
Configuration: Are env vars and config options correct?

Check for common spec errors:

Wrong package name (e.g., "react-query" vs "@tanstack/react-query")
Outdated API patterns (e.g., using deprecated functions)
Incorrect function signatures (e.g., wrong parameter order)
Missing required configuration (e.g., missing env vars)

Flag any mismatches.

Completeness

Check against requirements:

All requirements covered? - Each requirement should have implementation details
All acceptance criteria testable? - Each criterion should be verifiable
Edge cases handled? - Error conditions, empty states, timeouts
Integration points clear? - How components connect

Flag any gaps.

Consistency

Check within spec:

Package names consistent - Same name used everywhere
File paths consistent - No conflicting paths
Patterns consistent - Same style throughout
Terminology consistent - Same terms for same concepts

Flag any inconsistencies.

Feasibility

Check practicality:

Dependencies available? - All packages exist and are maintained
Infrastructure realistic? - Setup will work
Implementation order logical? - Dependencies before dependents
Scope appropriate? - Not over-engineered, not under-specified

Flag any concerns.

Requirements Alignment

Cross-reference with requirements:

Verified information used? - Spec should use researched facts
Unverified claims flagged? - Any assumptions marked clearly
Gotchas addressed? - Known issues handled
Recommendations followed? - Requirements suggestions incorporated

Flag any divergences.

Phase 3: Catalog Issues

Create a list of all issues found:

## Issues Found

### 1. [SEVERITY: HIGH] Package name incorrect

- **Spec says**: "[incorrect]"
- **Should be**: "[correct]"
- **Location**: Line 45, Requirements section

### 2. [SEVERITY: MEDIUM] Missing edge case

- **Requirement**: "Handle connection failures"
- **Spec**: No error handling specified
- **Location**: Implementation Notes section

### 3. [SEVERITY: LOW] Inconsistent terminology

- **Issue**: Uses both "memory" and "episode" for same concept
- **Location**: Throughout document

Phase 4: Fix Issues

For each issue found, fix it directly in the spec:

For each fix:

1. Make the change in spec 2. Verify the change was applied 3. Document what was changed

Phase 5: Create Critique Report

# Spec Critique Report

**Spec**: [spec-name]
**Date**: [timestamp]

## Summary

| Category               | Status    | Issues  |
| ---------------------- | --------- | ------- |
| Technical Accuracy     | PASS/FAIL | [count] |
| Completeness           | PASS/FAIL | [count] |
| Consistency            | PASS/FAIL | [count] |
| Feasibility            | PASS/FAIL | [count] |
| Requirements Alignment | PASS/FAIL | [count] |

## Issues Found and Fixed

### High Severity

1. [Issue] - FIXED: [what was changed]

### Medium Severity

1. [Issue] - FIXED: [what was changed]

### Low Severity

1. [Issue] - FIXED: [what was changed]

## No Issues Found (if applicable)

Spec is well-written with no significant issues found.

## Confidence Level

[HIGH/MEDIUM/LOW]

## Recommendations

- [Any remaining concerns or suggestions]

Phase 6: Verify Fixes

After making changes:

# Verify spec is still valid markdown
head -50 .claude/context/specs/[task-name]-spec.md

# Check key sections exist
grep -E "^##? Overview" spec.md
grep -E "^##? Requirements" spec.md
grep -E "^##? Success Criteria" spec.md

Severity Guidelines

HIGH - Will cause implementation failure:

Wrong package names
Incorrect API signatures
Missing critical requirements
Invalid configuration

MEDIUM - May cause issues:

Missing edge cases
Incomplete error handling
Unclear integration points
Inconsistent patterns

LOW - Minor improvements:

Terminology inconsistencies
Documentation gaps
Style issues
Minor optimizations

Category Definitions

Accuracy: Technical correctness (packages, APIs, config)
Completeness: Coverage of requirements and edge cases
Consistency: Internal coherence of the document
Feasibility: Practical implementability
Alignment: Match with original requirements

Verification Checklist

Before completing spec critique:

[ ] All sections analyzed with extended thinking
[ ] Technical accuracy verified
[ ] Completeness checked against requirements
[ ] Consistency verified throughout spec
[ ] Feasibility assessed
[ ] All issues cataloged with severity
[ ] All high/medium issues fixed
[ ] Critique report created
[ ] Spec still valid after fixes

Extended Thinking Prompt

When analyzing, think through:

"Looking at this spec, I need to deeply analyze it against the requirements...

First, let me check all package names. The requirements mention [X], but the spec says [Y]. This is a mismatch that needs fixing.

Next, looking at the API patterns. The requirements show initialization requires [steps], but the spec shows [different steps]. Another issue.

For completeness, the requirements mention [X, Y, Z]. The spec covers X and Y but I don't see Z addressed anywhere. This is a gap.

Looking at consistency, I notice '[term1]' and '[term2]' used interchangeably. Should standardize on one term.

For feasibility, the setup seems correct. The configuration matches.

Overall, I found [N] issues that need fixing before this spec is ready for implementation."

Common Mistakes

Surface-Level Review

Why it's wrong: Skimming misses critical issues.

Do this instead: Use extended thinking. Analyze each section deeply.

Reporting Without Fixing

Why it's wrong: Just listing issues doesn't improve the spec.

Do this instead: Fix issues directly. Make the spec better.

Integration with Other Skills

This skill works well with:

spec-writing: Provides the spec to critique
complexity-assessment: Helps determine if critique is needed
debugging: Use if spec critique reveals code issues

Iron Laws

1. NEVER approve a specification that contains contradictions, even minor ones 2. ALWAYS surface hidden assumptions explicitly — they are as important as stated requirements 3. NEVER let scope creep go unquestioned in a spec review 4. ALWAYS validate edge cases and error scenarios before approving 5. NEVER critique implementation approach — focus only on specification completeness and consistency

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Approving specs with contradictions	Downstream implementation resolves contradictions incorrectly	Flag all contradictions, even minor ones, before approval
Missing hidden assumptions	Assumptions become mismatched requirements during implementation	Explicitly surface every assumption the spec relies on
Skipping edge case review	Error scenarios discovered too late during implementation	Validate all boundary conditions and error paths in the spec
Critiquing implementation details	Distracts from specification quality; spec defines WHAT not HOW	Focus critique on completeness, consistency, and testability
Accepting vague success criteria	Delivery cannot be verified as complete	Require measurable, testable acceptance criteria for every requirement

Memory Protocol

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

'use strict';
/**
 * Post-execute hook for spec-critique
 * Auto-generated by enterprise-bundle-scaffolder
 *
 * Records metrics after skill execution.
 */

function postExecute(_context) {
  // Record execution metrics
  return { ok: true, skill: 'spec-critique' };
}

module.exports = { postExecute };

'use strict';
/**
 * Pre-execute hook for spec-critique
 * Auto-generated by enterprise-bundle-scaffolder
 *
 * Validates inputs before skill execution.
 */

function preExecute(context) {
  // Validate skill invocation context
  if (!context || typeof context !== 'object') {
    return { allow: true, message: 'spec-critique: no context to validate' };
  }
  return { allow: true };
}

module.exports = { preExecute };

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "spec-critique Input Schema",
  "description": "Input validation schema for spec-critique skill",
  "type": "object",
  "required": [],
  "properties": {},
  "additionalProperties": true
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "spec-critique Output Schema",
  "description": "Output validation schema for spec-critique skill",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the skill executed successfully"
    },
    "result": {
      "type": "object",
      "description": "The skill execution result",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Error message if execution failed"
    }
  },
  "additionalProperties": true
}

#!/usr/bin/env node

/**
 * Spec Critique - Main Script
 * Self-critique specification documents using extended thinking — surfaces hidden assumptions, contradictions, missing edge cases, and scope creep before implementation
 */

const options = Object.fromEntries(
  process.argv
    .slice(2)
    .filter(arg => arg.startsWith('--'))
    .map(flag => [flag.replace(/^--/, ''), true])
);

if (options.help) {
  console.log('Spec Critique - Main Script');
  process.exit(0);
}

console.warn('WARNING: This skill is currently a scaffold and has no implementation.');
process.exit(1);