# Spec Review

> Validate, critique, and iterate on generated specifications. Use when Codex should run the converted spec-review workflow.

- Skill: `artsmc/spec-review` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add artsmc/spec-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artsmc/spec-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: artsmc (https://skillmd.com/u/artsmc)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artsmc/spec-review

---


# Spec Review

Converted Claude skill workflow for Codex/OpenAI use.

## Source

Converted from `skills/spec-review/SKILL.md`.

## Converted Instructions

The content below was adapted from the Claude source. Rewrite tool and runtime assumptions as needed when they refer to Claude-only features.

# Spec Review: Critique & Iterate

Validate generated specifications, provide critical analysis, and collect user feedback.

## Purpose

This skill provides the **human feedback loop** for feature specifications:
1. Validate spec completeness (automated)
2. Critique quality (automated)
3. Present findings to user
4. Iterate based on feedback

## Workflow

### Phase 1: Validate Structure

Run automated validation to catch errors early:

```bash
Bash: python skills/spec/scripts/validate_spec.py /path/to/job-queue/feature-{name}
```

**Checks performed:**
- ✅ All required files exist (FRD, FRS, GS, TR, task-list)
- ✅ Files not empty (> 100 bytes)
- ✅ Gherkin syntax valid
- ✅ Task list has actionable items
- ✅ .gitignore includes /job-queue
- ✅ Cross-references consistent

**Output:** JSON with errors, warnings, completeness score

### Phase 2: Critique Quality

Run automated critique for quality analysis:

```bash
Bash: python skills/spec/scripts/critique_plan.py /path/to/job-queue/feature-{name}
```

**Analysis performed:**
- **Requirement Quality:**
  - Are requirements specific or vague?
  - Are acceptance criteria measurable?
  - Are edge cases covered?

- **Task Breakdown:**
  - Are tasks atomic and actionable?
  - Is sequencing logical?
  - Are dependencies identified?

- **Technical Design:**
  - Are APIs well-defined?
  - Are data models complete?
  - Are error scenarios handled?
  - Are security concerns addressed?

- **Testability:**
  - Can Gherkin scenarios be automated?
  - Are test data requirements clear?

**Output:** JSON with critique score, critical issues, warnings, recommendations

### Phase 3: Present Findings

Summarize validation and critique results for user:

#### If Validation FAILED (errors found):

```
⚠️ Spec Validation Failed

Critical Errors:
- [List errors from validation tool]

Warnings:
- [List warnings]

Completeness Score: [X%]

Action Required:
These issues must be fixed before proceeding. Would you like me to:
1. Fix these issues automatically
2. Re-run `spec-writer` skill with corrections
3. Guide you to fix them manually
```

#### If Validation PASSED but Critique Found Issues:

```
✅ Spec Structure Valid

Quality Analysis (Score: [X%]):

Critical Issues:
- [File] - [Issue] → Suggestion: [fix]

Warnings:
- [File] - [Issue] → Suggestion: [improvement]

Recommendations:
- [List recommendations]

---

The specs are structurally valid but have quality concerns.
Would you like me to iterate on these issues?
```

#### If Everything PASSED:

```
✅ Spec Validation Passed
✅ Quality Critique Passed (Score: [X%])

Generated Specifications:
📁 /job-queue/feature-{name}/docs/
  ├── FRD.md - Business requirements ✅
  ├── FRS.md - Functional specs ✅
  ├── GS.md - Gherkin scenarios ✅
  ├── TR.md - Technical requirements ✅
  └── task-list.md - Development tasks ✅

Completeness: [X%]
Quality Score: [X%]

Minor Recommendations:
- [Optional improvements]

Ready to proceed with development?
```

### Phase 4: Collect User Feedback

Ask the user for their assessment:

**Questions:**
1. Are these specifications acceptable?
2. Any changes or clarifications needed?
3. Should I iterate on any specific areas?

**User Options:**

**A) Approve Specs**
→ Mark as complete, ready for development

**B) Request Changes**
→ Collect specific feedback, re-run `spec-writer` skill with updates

**C) Manual Edits**
→ User will edit files directly, re-run validation after

**D) Focus on Specific Area**
→ Re-run critique with `--focus` on specific concerns

### Phase 5: Iterate if Needed

If user requests changes:

1. **Collect specific feedback:**
   - Which documents need changes?
   - What's missing or incorrect?
   - Any new requirements?

2. **Re-run `spec-writer` skill:**
   ```bash
   delegation workflow with skill="spec-writer"

   Prompt: "Update feature specifications based on feedback:

   **Previous Specs:** /job-queue/feature-{name}/docs/

   **User Feedback:**
   [List specific changes requested]

   **Focus Areas:**
   [Which documents to update]

   Please update the specifications addressing this feedback."
   ```

3. **Re-run validation and critique:**
   - Validate structure again
   - Critique quality again
   - Present updated findings

4. **Repeat until approved**

## Tools Used

### Python Scripts

1. **validate_spec.py** - Structural validation
   - File existence and completeness
   - Gherkin syntax
   - Cross-references

2. **critique_plan.py** - Quality critique
   - Requirement clarity
   - Task quality
   - Technical completeness
   - Testability

## Decision Tree

```
Start → Run Validation
  ├─ Errors? → Present errors → User fixes → Re-validate
  └─ Valid → Run Critique
      ├─ Critical Issues? → Present issues → User decides
      │   ├─ Iterate → Re-run agent → Re-validate
      │   └─ Accept → Done
      └─ No Critical Issues → Present summary → User approves → Done
```

## Expected Outcomes

After this skill completes:

1. ✅ Specs validated for structure
2. ✅ Specs critiqued for quality
3. ✅ Findings presented to user
4. ✅ User feedback collected
5. ✅ Specs iterated if needed
6. ✅ Final specs approved by user

## Next Steps

Once specs are approved:

1. **Update Memory Bank:**
   ```bash
   $memorybank-sync
   ```

2. **Begin Development:**
   - Follow task-list.md
   - Reference TR.md for technical details
   - Use GS.md for test scenarios

## Important Notes

- **Human-in-loop:** User approval required before proceeding
- **Automated validation:** No manual checklists
- **Critical analysis:** Quality gate before development
- **Iteration support:** Easy to refine based on feedback

---

**Estimated time:** 2-5 minutes for validation + user review
**Token usage:** ~600 tokens (focused on validation and feedback)