Review Types (15 total)
| Type |
Agent |
Focus |
code-quality |
code-reviewer |
Logic, error handling, quality |
test-quality |
test-quality-auditor |
Coverage, test quality |
security |
code-reviewer |
Vulnerabilities, auth |
perf |
performance-auditor |
N+1, loops, caching |
acceptance |
acceptance-verifier |
Criteria verification |
sqlite |
sqlite-reviewer |
Transactions, SQL injection |
path-security |
path-security-reviewer |
Path traversal, symlinks |
subprocess |
subprocess-reviewer |
Command injection, timeouts |
state-machine |
state-machine-reviewer |
State transitions, races |
hook |
hook-reviewer |
Validator registration |
tui |
tui-reviewer |
Reactive bindings, widgets |
schema |
schema-reviewer |
Validation bypass, limits |
error-handling |
error-handling-reviewer |
Exception patterns |
api-client |
api-client-reviewer |
HTTP, API keys, retry |
input-validation |
input-validation-reviewer |
Size limits, types |
Severity Levels
| Level |
Meaning |
Gate |
clean |
No issues |
Pass |
minor |
Non-blocking |
Pass |
major |
Significant issues |
Block |
critical |
Immediate fix needed |
Block |
Core APIs
Check Missing Reviews
from formaltask.review.gate import get_missing_reviews
from formaltask.epics.repository import EpicRepository
repo = EpicRepository(db_path)
missing = get_missing_reviews(task_id, repo)
# Returns: ["code-quality", "security"]
Check and Inject Reviews
from formaltask.review.gate import check_and_inject_reviews
passed, instructions = check_and_inject_reviews(task_id, repo, skip_review=False)
# passed=True, None: All reviews present
# passed=False, instructions: Missing, instructions provided
ReviewPacket Schema
from formaltask.review.packet_schema import ReviewPacket
packet = ReviewPacket(
task_id=42,
review_type="code-quality",
severity="clean",
findings=[
{"file": "src/auth.py", "line": 42, "priority": "P1",
"category": "error-handling", "description": "Missing timeout"}
],
summary="Found 1 issue" # Max 200 chars
)
Output Format
@@@REVIEW
{"task_id": 42, "review_type": "code-quality", "severity": "minor", ...}
@@@REVIEW
Database Schema
CREATE TABLE task_reviews (
task_id INTEGER NOT NULL,
review_type TEXT NOT NULL,
severity TEXT NOT NULL CHECK (severity IN ('clean','minor','major','critical')),
findings TEXT NOT NULL, -- JSON array
reviewed_at TEXT NOT NULL,
round INTEGER NOT NULL DEFAULT 1,
reviewed_sha TEXT,
PRIMARY KEY (task_id, review_type, round)
);
Review Gate Flow
task-complete attempted- Gate checks
required_reviews in task metadata
- Missing reviews → inject instructions
- Agent runs review, outputs
@@@REVIEW
- Packet stored via
review-store CLI
- Gate re-checks → passes if
clean or minor
Common Patterns
Check if Task Has Passing Review
cursor.execute("""
SELECT severity FROM task_reviews
WHERE task_id = ? AND review_type = ?
ORDER BY round DESC LIMIT 1
""", (task_id, "code-quality"))
row = cursor.fetchone()
if row and row["severity"] in ("clean", "minor"):
print("Review passes gate")
Store Review
ft review store '<JSON>'
Related Modules
| Module |
Purpose |
formaltask.review.gate |
Gate logic, instruction generation |
formaltask.review.packet_schema |
ReviewPacket, ReviewType, SeverityLevel |
formaltask.review.context |
Context for re-reviews |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: managing-reviews3description: This skill should be used when working with the FormalTask review system. Use when this capability is needed.4---56<role>7WHO: Review system navigator8ATTITUDE: Reviews that don't block are opinions. Blocking reviews are quality gates.9</role>1011<purpose>12Your job is to help navigate the FormalTask review system—types, gates, storage, and APIs. When reviews block, understand why. When they pass, understand what passed.13</purpose>1415## Review Types (15 total)1617| Type | Agent | Focus |18|------|-------|-------|19| `code-quality` | code-reviewer | Logic, error handling, quality |20| `test-quality` | test-quality-auditor | Coverage, test quality |21| `security` | code-reviewer | Vulnerabilities, auth |22| `perf` | performance-auditor | N+1, loops, caching |23| `acceptance` | acceptance-verifier | Criteria verification |24| `sqlite` | sqlite-reviewer | Transactions, SQL injection |25| `path-security` | path-security-reviewer | Path traversal, symlinks |26| `subprocess` | subprocess-reviewer | Command injection, timeouts |27| `state-machine` | state-machine-reviewer | State transitions, races |28| `hook` | hook-reviewer | Validator registration |29| `tui` | tui-reviewer | Reactive bindings, widgets |30| `schema` | schema-reviewer | Validation bypass, limits |31| `error-handling` | error-handling-reviewer | Exception patterns |32| `api-client` | api-client-reviewer | HTTP, API keys, retry |33| `input-validation` | input-validation-reviewer | Size limits, types |3435---3637## Severity Levels3839| Level | Meaning | Gate |40|-------|---------|------|41| `clean` | No issues | Pass |42| `minor` | Non-blocking | Pass |43| `major` | Significant issues | **Block** |44| `critical` | Immediate fix needed | **Block** |4546---4748## Core APIs4950### Check Missing Reviews5152```python53from formaltask.review.gate import get_missing_reviews54from formaltask.epics.repository import EpicRepository5556repo = EpicRepository(db_path)57missing = get_missing_reviews(task_id, repo)58# Returns: ["code-quality", "security"]59```6061### Check and Inject Reviews6263```python64from formaltask.review.gate import check_and_inject_reviews6566passed, instructions = check_and_inject_reviews(task_id, repo, skip_review=False)67# passed=True, None: All reviews present68# passed=False, instructions: Missing, instructions provided69```7071---7273## ReviewPacket Schema7475```python76from formaltask.review.packet_schema import ReviewPacket7778packet = ReviewPacket(79 task_id=42,80 review_type="code-quality",81 severity="clean",82 findings=[83 {"file": "src/auth.py", "line": 42, "priority": "P1",84 "category": "error-handling", "description": "Missing timeout"}85 ],86 summary="Found 1 issue" # Max 200 chars87)88```8990### Output Format9192```93@@@REVIEW94{"task_id": 42, "review_type": "code-quality", "severity": "minor", ...}95@@@REVIEW96```9798---99100## Database Schema101102```sql103CREATE TABLE task_reviews (104 task_id INTEGER NOT NULL,105 review_type TEXT NOT NULL,106 severity TEXT NOT NULL CHECK (severity IN ('clean','minor','major','critical')),107 findings TEXT NOT NULL, -- JSON array108 reviewed_at TEXT NOT NULL,109 round INTEGER NOT NULL DEFAULT 1,110 reviewed_sha TEXT,111 PRIMARY KEY (task_id, review_type, round)112);113```114115---116117## Review Gate Flow1181191. `task-complete` attempted1202. Gate checks `required_reviews` in task metadata1213. Missing reviews → inject instructions1224. Agent runs review, outputs `@@@REVIEW`1235. Packet stored via `review-store` CLI1246. Gate re-checks → passes if `clean` or `minor`125126---127128## Common Patterns129130### Check if Task Has Passing Review131132```python133cursor.execute("""134 SELECT severity FROM task_reviews135 WHERE task_id = ? AND review_type = ?136 ORDER BY round DESC LIMIT 1137""", (task_id, "code-quality"))138row = cursor.fetchone()139140if row and row["severity"] in ("clean", "minor"):141 print("Review passes gate")142```143144### Store Review145146```bash147ft review store '<JSON>'148```149150---151152## Related Modules153154| Module | Purpose |155|--------|---------|156| `formaltask.review.gate` | Gate logic, instruction generation |157| `formaltask.review.packet_schema` | ReviewPacket, ReviewType, SeverityLevel |158| `formaltask.review.context` | Context for re-reviews |159160<rules>161- Blocking reviews are quality gates - not suggestions162- clean/minor pass, major/critical block163- @@@REVIEW format is required - agents must output this164- round field tracks re-reviews - same type can run multiple times165</rules>166167---168> Converted and distributed by [TomeVault](https://tomevault.io/claim/davidabeyer) — claim your Tome and manage your conversions.169<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io