review-protocol

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 spec
• specs/drafting/ — intents being specced
• specs/ready/ — specced and awaiting builder
• specs/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:

1. Recurring failure patterns (systemic risk)
2. Unmet values (structural misalignment)
3. Blueprint gaps (missing promised capability)
4. Skill gaps (agent capability deficit)
5. Logical follow-ups (incremental improvement)
6. 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:

1. Choose a brief slug: {topic}-{aspect}.md (e.g., missing-verifier-skills.md, value-transparency-gap.md)
2. Check the slug doesn't collide with any existing file in specs/inbox/, specs/drafting/, specs/ready/, specs/archive/
3. 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