---
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.

```markdown
# [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.