oh-my-skills/skills/create-docs/specs-reviewer.md

---

name: specs-reviewer

description: Review Technical Documentation Maintenance Agent skill

Objective: Review the project documentation and remove obsolete or outdated specifications, aligning it with the current state of the code.

Instructions:

• Todo list: initial list of the operations you will perform.
• Working mode: spawn parallel agents on different files.
• Read the AGENTS.md file and all files contained in the specs/ folder.
• Find stale notes first: base the review only on the files present in source (no version-control commands; the codebase is read-only, all edits go to the vault). Review first the notes whose sources files are missing or have a last-modified date later than verified_date, or with empty verified_date; set them back to status: draft until re-verified.
• Identify any specification, behavior, API, or description that no longer matches the current code. Pay special attention to these noted changes:
• For each occurrence of outdated information:
  • Delete or rewrite the content to reflect the current behavior;
  • If the specification mentions the old behavior, update or remove it;
• REST API / SOAP: document payloads, responses and error codes of every APIs exposed from the backend, if developed in codebase.
• Do not modify sections that are still accurate and aligned with the code.
• Obsidian format: keep every note compliant with SKILL.md section 7 (frontmatter, unique file names, wikilinks, MOC links); fix broken [[links]].
• Re-verify: run SKILL.md section 8 on every changed domain note, then update verified_date and the domain-inventory.md row.
• Language: verify that the documentation language is English; if not, correct it.
• Review: once the plan is created, review it until you are satisfied. If it's even 95% done, redo it until it is 100% done.
• Final output: List a brief summary of the modified files and the changes made, along with a todo list.
• Verify written files: verify the written files.

---

Target Structure Template:

Each spec file follows this structure. Sections present only when they have content.

# [Domain]

## Conventions & Gotchas
- [only things an LLM would get wrong by default]

## API
- [endpoint → request/response format, one line each]

## Key Classes
- [ClassName → constructor signature + public methods, one line]

## Schema
- [table: columns and constraints, compact format]

## Dependencies
- [if you modify X → also update Y]

## Common Errors
- [known error pattern → cause → fix]

Rest api format example:

### PUT - /api/conversations/@id

payload {title: string}
response - 200 - {id: int, title: string, created_at: string} — strip control chars, collapse whitespace, max 200 chars (mb_substr)
response - 400 - {message: "Invalid ID"} — id <= 0
response - 400 - {message: "Title is required"} — empty after trim
response - 403 - {message: "Access denied"} — not owner

---

User-facing language: Italian. Documentation language: English.

Attention: Do not introduce new features. Only align the documentation with the existing code.