roi-outline

Files (1)

• SKILL.md

SKILL.md (first lines)

# roi:outline — generate plans

This skill turns a clarified brief into one or more **executable plans**
with waves, dependencies, and verification targets. It owns one stage:
**read brief → generate plans → confirm storage → next-step pointer**.

A plan is what `roi:go` implements. Each plan has:

- `actions` — outcome-oriented changes the implementation must achieve.
- `verification_targets` — falsifiable oracles (commands, builds, greps)
  that prove the actions landed.
- `dependencies` — plan UUIDs this plan depends on (waits until those
  pass).
- `wave` — integer ordering for parallelizable batches.

**Read first when planning for agents:**
[`references/agentic-plan-strength.md`](../references/agentic-plan-strength.md)
covers outcome strength, binding altitude, and property-style verification.

## Inputs

1. **Mission ID** required.
2. **Optional inline Plan text** — output pasted or carried in-context from
   Codex Plan mode, Copilot, Claude Code, Cursor, CE, or Markdown. Run
   `plan_normalize` first; use `normalized.plans` as the draft plan array
   after applying this skill's quality checks.
3. **Optional source artifact** — a CE plan, maturity requirements doc, or
   convergence seam manifest. When present, **import** constraints and
   properties from it; do not re-scope in ROI. If its acceptance bullets
   must survive execution, mark affected plans with `source_contract_refs`
   and `requires_source_contract_check: true`.
4. **Optional plans array** — when the operator already has a draft plan
   structure, pass it directly to `plan_generate`.

## Procedure

1. Read the brief and any prior plans:

   ```bash
   node roi/scripts/lifecycle.mjs brief_get_latest '{"mission_id":"<id>"}'
   node roi/scripts/lifecycle.mjs plan_list '{"mission_id":"<id>"}'
   ```

2. **Validate brief inventory against the live tree.** Before composing
   plans, re-derive every quantitative claim in the brief from the actual
   codebase. Briefs frequently undercount because they were seeded from
   chat memory or a prior mission's notes — see
   `roi-clarify` "Evidence discipline."

   For each quantitative claim in `success_criteria`, `constraints`, or
   `assumptions`:

   - Run the citation command if the brief carries one. If the brief carries
     no citation, derive one now (typically `rg -l <pattern> <scope>`).
   - Compare the live count against the brief's count. If the live tree
     reveals more importers, files, call sites, or affected packages than
     the brief named, **stop and `brief_revise`** before planning. Don't
     paper over the gap with bigger per-plan actions.
   - Inventory every importer/caller/path the plans will need to touch.
     Write them down (in the brief or in a scratch note) so the planner
     can reason about plan boundaries against an accurate footprint, not
     a stale one.

   **Why:** plans inherit the brief's inventory. If the brief says "5
   importers across 4 files" and reality is 17 across 9, the planner will
   compose actions and oracles scoped to the 4 named files, every oracle
   will pass during `roi:go`, and the mission-level invariant
   ("core does not import UI") will still be violated by the 5 unnamed
   files. The planner-stage discovery cost is O(minutes); the
   post-`roi:go` cost is O(hours) of partial-completion cleanup.

   **Stop conditions for this step:**

   - Brief carries an unsourced quantitative claim → `brief_revise` to mark
     it `assumed: true` and move it to `open_questions`, *or* derive it now
     and rewrite the brief with the citation.
   - Live tree count diverges materially from the brief → `brief_revise`
     before `plan_generate`. Document the divergence in the new revision
     so the trail is durable.
   - Brief contains no quantitative claims → skip this step.

   Counts in this inventory are scope telemetry only. They can expose stale or
   incomplete discovery, but no count, percentage, score, or ContextPack TTL
   proves that planning orientation is sufficient. Sufficiency requires
   owner-seam coverage and disposition of every material uncertainty.

3. **Resolve scope-affecting open_questions in the brief, not the plan.**
   Read every entry in the brief's `open_questions`. For each entry, ask:
   *would its answer change which files the plans touch, which subsystems
   are excluded, or the count of importers a plan must rewrite?* If yes,
   it is **scope-affecting** and must be resolved before `plan_generate`.

   Resolution paths (try in order):

   1. **Run the discovery command.** Most scope questions reduce to "what
      does the live tree contain?" — run the `rg` / `go list` / equivalent
      now and call `brief_revise` to record the answer as a constraint or
      non_goal. The question disappears from `open_questions` because it
      is answered.
   2. **Ask the operator once.** When the question genuinely requires
      operator judgment ("treat package X as honorary UI?"), ask once,
      capture the answer in `brief_revise`, then continue. Do **not**
      defer the question into a plan with "deferred decoupling" comments
      or allowlist entries that catalog the ambiguity.
   3. **Stop and report** if the brief is too unsettled to ground a plan.
      Returning the operator to `roi:clarify` is preferable to writing
      plans that inherit the confusion.

   **Failure mode this prevents:** plans that allowlist or comment-out
   ambiguity ("// TODO: confirm with operator whether uireplay is core")
   make the plan a catalog of unresolved scope decisions instead of an
   instruction set. `roi:go` then asks the operator scope questions at
   execute time, which is the most expensive moment to ask. The plan is
   the clarification — it must commit to a position, not list options.

   **Stop conditions for this step:**

   - At least one `open_questions` entry is scope-affecting and unresolved
     → resolve it now via discovery or operator interaction; rewrite the

From instagrim-dev/roir, MIT.

More from instagrim-dev/roir