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

Project Research

When to Use

When Vision is approved and implementation options need to be investigated.

Inputs

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

Prerequisite

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

Context Boundary

Read only: Vision. Spec, Plans, and Execute_State do not exist yet.

Procedure

  1. Read the Vision document
  2. Copy Forge/Forge_Project/Skills/Project_Create/templates/Research_Template.md to {Project}_Research.md in the project folder
  3. Update {Project}_Phase.md: set Phase: Research_Started
  4. For each requirement or group of related requirements that need investigation:
    • Research implementation options (web search, docs, existing codebase)
    • Document findings, options with pros/cons, and a recommendation
    • Mark the Decision subsection as pending user approval
  5. Update document status to review
  6. Add sidebar entry by spawning the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' }
  7. Build, commit, push
  8. Present all decision points to the user for review
  9. Record user decisions with “Decided by: @name — date” attribution
  10. All decisions must be approved before proceeding to Spec phase
  11. Iterate until the user approves all decisions
  12. Update document status to approved
  13. Update {Project}_Phase.md: set Phase: Research_Completed
  14. Build, commit, push

Rules

  • Research documents are mutable until approved — update findings and recommendations in-place when they change
  • After approval, use dated revision notes for any changes
  • Never append notes about previous drafts or abandoned alternatives (“Note: The previous draft recommended…”)
  • If a decision rationale needs preservation before approval, put it in Learnings, not Research
  • Decision points must be clearly marked and easy to review
  • Each decision records who decided and when
  • If a requirement has an obvious solution with no alternatives, document it briefly and mark as decided