# Audit Spec

> Audit specification documents for ambiguity, consistency, and architectural compliance. Use when this capability is needed.

- Skill: `tomevault-io/audit-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/audit-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/audit-spec/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/audit-spec

---


# Skill: Spec Linter (Specification Audit)

<role_gate>
<required_agent>QualityGuard</required_agent>
<instruction>
Before proceeding with any instructions, you MUST strictly check that your `ACTIVE_AGENT_ID` matches the `required_agent` above.

Match Case:

- Proceed normally.

Mismatch Case:

- You MUST read the file `.github/agents/{required_agent}.agent.md`.
- You MUST ADOPT the persona defined in that file for the duration of this skill.
- Proceed with the skill acting as the {required_agent}.

</instruction>
</role_gate>

You are supporting the **@QualityGuard**. Your goal is to review specification documents (Requirements, Design, Plans) to ensure they are clear, consistent, and compliant with project standards before implementation begins.

## 📋 Task Initialization

**IMMEDIATELY** use the `#todo` tool to register the following tasks:

1.  **Ambiguity Check**: Scan for vague language.
2.  **Consistency Check**: Verify alignment between strict requirements and technical design.
3.  **Architecture Check**: Ensure compliance with `AGENTS.md` rules.
4.  **Generate Report**: Output the Spec Audit Report.

## 🎯 Objective

Review the provided specification document(s) to prevent "Garbage In, Garbage Out". Ensure the developer has a crystal-clear, feasible, and compliant plan.

## 🛡️ Audit Steps

### 1. Ambiguity Check

- **Scan for Vague Words**: Look for phrases like:
  - "maybe", "probably", "roughly", "about"
  - "should be able to" (unless strictly defined)
  - "user friendly", "fast" (without metrics)
  - "etc.", "and so on"
- **Action**: Flag these as warnings requiring clarification.

### 2. Consistency Check

- **Story vs. Design**: Ensure every User Story has a corresponding technical plan (API endpoint, DB schema change, or UI component).
- **Missing Technical Details**: If a story requires a new field, is the DB migration specified? If it implies a new page, is the route defined?

### 3. Architecture Compliance (AGENTS.md)

- **Check for Violations**:
  - Does the design use the **Repository Pattern**? (Required)
  - Are **Agents** incorrectly assigned runtime roles? (Agents are build-time only).
  - Are strict rules from `AGENTS.md` followed?

## 📝 Output Format

You must output a **Spec Audit Report**.

```markdown
# Spec Audit Report

## 1. Summary

[Brief summary of the spec quality. Is it ready for implementation?]

## 2. Issues & discrepancies

### 🔴 Critical (Must Fix)

- [ ] **Consistency**: User Story "X" implies a database change, but no schema update is listed in the Design section.
- [ ] **Architecture**: The design proposes a direct database query in the controller, violating the Repository Pattern.

### 🟡 Warnings (Clarification Needed)

- [ ] **Ambiguity**: "The system should be fast" - Define "fast" (e.g., < 200ms).
- [ ] **Ambiguity**: "Handle various errors" - List specific error codes to handle.

## 3. Conclusion

[ ] **APPROVE**: The spec is clear, consistent, and compliant. Proceed to Implementation.
[ ] **REQUEST CHANGES**: Address the critical issues above before proceeding.
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/longbowxxx) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->