Skip to content
Uvilo OS
published Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Project Spec Eval

When to Use

After writing a Spec, before presenting for approval. Run by a Project Evaluator — not the same agent who wrote the Spec.

Inputs

  • Project path ({Dept}/Projects/{Project}/)
  • Vision document
  • Research document
  • Spec document

Context Boundary

Read only: Vision, Research, and Spec. No other project documents.

Prerequisite

HARD GATE: If you are in the same session that wrote the Spec, STOP. Tell the user: “Spec evaluation requires an independent reviewer — please start a new conversation and run Spec Eval there.” Do NOT proceed with evaluation.

HARD GATE: Verify {Project}_Vision.md exists and contains R-numbered Requirements (R1, R2, …) and V-numbered Success Criteria (V1, V2, …). If the Vision is missing or lacks R-numbers/V-criteria, STOP. Report: “Cannot evaluate Spec traceability — no R-numbered requirements found in Vision. Create a proper Vision document first.”

Phase Names

  • Start: Spec_Eval_Started
  • End: Spec_Eval_Completed

Checklist

  1. Every requirement addressed — each R-number in the Vision maps to at least one Spec section. If there are no R-numbers in the Vision, this check FAILS — absence of requirements means traceability cannot be verified. Do not mark ✅ with a footnote; report the missing R-numbers as a finding
  2. No orphan sections — every Spec section traces back to a requirement
  3. Declarative — describes target state and behaviors, not build steps. Describing what a command/tool produces (inputs → outputs → guarantees) is behavioral description, not procedure
  4. Self-contained — a reader can understand the target system from the Spec alone and linked references
  5. No internal contradictions — include/exclude lists, budgets, and cross-references are consistent
  6. Research decisions reflected — no drift or re-litigation from approved Research
  7. Success criteria achievable — if the Spec were implemented as written, every V-criterion would pass. If there are no V-criteria in the Vision, this check FAILS — absence of success criteria means achievability cannot be verified. Do not mark ✅ with a footnote; report the missing V-criteria as a finding
  8. Naming consistent — names the Spec introduces or redefines are used consistently. Out-of-scope names merely referenced are not flagged
  9. Exact content preserved — when Research or Vision specifies exact text (prompts, configs, messages), it is linked via References/ rather than paraphrased
  10. No hidden scope — behaviors and constraints are stated explicitly. “Update all references” after a rename is self-scoping and not flagged. Only flag when something is implied but not stated

Procedure

  1. Read the Spec, Vision, and Research documents
  2. Update {Project}_Phase.md: set Phase: Spec_Eval_Started
  3. Build, commit, push
  4. Run each checklist item, marking ✅ or ⚠️ with a brief note
  5. Format findings using Forge/Forge_Project/Skills/Project_Create/templates/Spec_Eval_Template.md:
    • Replace variables with project values
    • No findings: Set Verdict to Approved, omit the Items table
    • Findings exist: Set Verdict to Rejected or Conditionally Approved, populate Items and Resolution Log
  6. Write findings to {Project}_Spec_Eval.md (create or overwrite)
  7. Add sidebar entry for the report by spawning the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } (placed under the project’s documents group)
  8. Build, commit, push
  9. If findings exist — auto-fix loop:
    • Set {Project}_Phase.md: set Phase: Spec_Eval_Blocked
    • Spawn the Thinker to fix the specific findings in the Spec document
    • The Thinker sets Spec_Started, fixes the Spec, sets Spec_Completed, and re-spawns the Evaluator
    • On re-entry, set Phase: Spec_Eval_Started and re-evaluate; iterate up to 3 rounds
    • Only escalate to the user when Thinker and Evaluator cannot converge (after 3 rounds, or when findings involve genuine ambiguity or trade-off decisions) If no findings (or auto-fix converged): Update {Project}_Phase.md: set Phase: Spec_Eval_Completed
  10. Update frontmatter status to approved in both the Spec document and the Spec_Eval report
  11. Build, commit, push

Rules

  • Flag only real issues — not theoretical ones. If a checklist item passes on its own terms, mark ✅ even if the pattern could be a problem in other contexts
  • Out-of-scope names and self-scoping references are not issues
  • The report file is durable review history — it persists across reruns and is not deleted when the project returns to Spec
  • An independent reviewer must run this phase — never the same agent/session that wrote the Spec
  • The auto-fix loop should resolve most findings without user involvement. Only genuine ambiguities or creative decisions require human input