| name | review-protocol |
| description | The reviewer agent's structured process for identifying factory improvement opportunities and generating evidence-backed intents. |
Purpose
Generate well-formed intent files for the human to curate. Your job is observation and identification — not execution. The human decides what gets built.
The Review Process
Step 1: Deduplication Check (always first)
Before identifying anything, read:
specs/inbox/ — pending intents awaiting specspecs/drafting/ — intents being speccedspecs/ready/ — specced and awaiting builderspecs/archive/ — completed specs (reference)
Note what topics are already addressed. Do not generate competing or duplicate intents. If an existing intent partially addresses a concern, note it in your daily log but do not generate a competing intent.
Step 1.5: Needs Escalation Check
Read memory/*/needs.md across all agent directories.
For any entry where status: open and the created timestamp is more than 2× your heartbeat interval in the past, note it in your review output as an escalated item. Format:
Escalated need: {id} [{agent}, created {timestamp}]
{blocked field}
This is informational — you cannot resolve needs entries. The human runs factory needs to see the full list and factory needs --resolve {id} after acting.
Do not generate a competing intent if the blocker is already captured in a needs entry.
Step 2: Review Categories (in priority order)
Work through these categories. Stop at 3 high-quality intents — do not exhaust all categories if you've already found 3 worth generating.
1. Failure Patterns
Read learnings/failures/. Look for:
- Same failure category appearing 2+ times (naming convention:
{date}-{project}-{summary}.md)
- Patterns that suggest systemic fix rather than individual patches
- Failure types without corresponding skills or conventions to prevent recurrence
Intent candidate: recurring theme with 2+ entries, no existing fix in skills/ or specs.
2. Value Alignment
Read universe/values.md. For each value:
- Is there evidence the factory embodies it in its current structure?
- Is any value explicitly contradicted by current behavior or missing capability?
Intent candidate: value that has no structural support and no existing spec addressing it.
3. Blueprint Gaps
Read universe/synthesis/factory-blueprint.md. Check:
- Which capabilities or bootstrap steps does the blueprint describe?
- Which have no corresponding spec (in any specs/ subdirectory) or verified task?
Intent candidate: described capability with no evidence of implementation or planned work.
4. Skill Coverage
Scan skills/{agent}/ directories. For each agent in agents.yaml with available skills listed:
- Does the corresponding
skills/{agent}/{skill-name}/SKILL.md exist with content?
- Or is it only a
.gitkeep (i.e., listed but unbuilt)?
Also check: which agents have daily logs (memory/daily/{agent}/) but have only the shared skill set?
Intent candidate: skill listed in agents.yaml but with no SKILL.md content. Cite the specific agent and skill name.
5. Completed Work Audit
Read specs/archive/ and tasks/verified/. Look for:
- Builder notes or verification reports mentioning known follow-ups
- Logical next steps that haven't been initiated (no corresponding spec or task)
- Features built that depend on something not yet built
Intent candidate: explicit follow-up mention in verified work with no existing spec.
6. Memory Coherence
Read memory/shared/KNOWLEDGE.md and memory/shared/PROJECTS.md. Look for:
- Stale entries describing things that no longer exist or have changed
- Active work with no PROJECTS.md entry
- Contradictions between KNOWLEDGE.md conventions and actual filesystem state
Intent candidate: concrete inconsistency or stale entry.
Step 3: Prioritization (if > 3 candidates found)
Rank by impact:
- Recurring failure patterns (systemic risk)
- Unmet values (structural misalignment)
- Blueprint gaps (missing promised capability)
- Skill gaps (agent capability deficit)
- Logical follow-ups (incremental improvement)
- Memory inconsistencies (housekeeping)
Generate the top 3. Log the rest in your daily log for next run.
Step 4: Generate Intent Files
For each intent to generate:
- Choose a brief slug:
{topic}-{aspect}.md (e.g., missing-verifier-skills.md, value-transparency-gap.md)
- Check the slug doesn't collide with any existing file in specs/inbox/, specs/drafting/, specs/ready/, specs/archive/
- Write to
specs/inbox/{slug}.md:
<!-- generated by: reviewer | run: {YYYY-MM-DD}T{HH:MM} | evidence: {brief citation} -->
# {working-title}
## What I'm Seeing
[Concrete observations with file/directory references — be specific]
## What I Want to See
[Desired end state — describe the outcome, not the implementation]
Step 5: Daily Log Entry
Write to memory/daily/reviewer/{YYYY-MM-DD}.md:
## {HH:MM} — Review Run
**Categories reviewed**: [list all reviewed]
**Candidates identified**: [count]
**Intents generated**: [list slugs]
**Deferred**: [list topics not generated, with reason]
**Skipped (duplicate)**: [list topics already addressed]
If NO_REPLY: note what was reviewed and why nothing was generated.
Evidence Requirements
Every "What I'm Seeing" section must reference:
- Specific file paths (e.g.,
skills/verifier/scenario-evaluation/ contains only .gitkeep)
- Directory states with item counts where relevant
- Learning entry filenames for failure patterns
- Quote-level citations from values.md or blueprint.md where applicable
Generic observations ("the factory lacks X") without file/directory evidence are not acceptable.
Hard Constraints
- 3-intent limit: per run, not per category
- No self-referential intents: do not generate intents about your own capabilities or existence
- No agents.yaml proposals: generate intents describing desired agent changes; the human modifies agents.yaml
- No projects/ access: your scope is factory structure, not codebases
- Read-only everywhere except: specs/inbox/, memory/reviewer/, memory/daily/reviewer/, skills/proposed/
- NO_REPLY when nothing found: do not generate trivial or speculative intents to appear productive
