diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md index 4756f66..34ca336 100644 --- a/config/opencode/commands/workflow.md +++ b/config/opencode/commands/workflow.md @@ -459,17 +459,44 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and - Add a comment of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit ` (date from the shell, never fabricated). - Propagate any status flip to the dependent index: `TODO/README.md` for top-level issues (`parent: null`), or the parent file's `## Sub-issues` line for sub-issues. - If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off (flip `- [ ]` to `- [x]` under `## Acceptance criteria`). -- Commit the TODO/ changes as a separate atomic commit: `chore(todo): update status and progress`. Stage the issue file plus any propagated index file (README.md or parent file). + +### File Follow-ups + +Tracked-worthy unresolved items must become real TODO issues; otherwise they vanish into the per-run `summary.md` and the user (who has walked away) never sees them. Before writing the summary, scan the run for items in these categories and dispatch `@pm` to file each as a **sub-issue of the current issue** (`parent: $ISSUE_ID`). + +| Source | New issue label | Title style | +|---|---|---| +| Pre-existing bug discovered while working but out of scope (e.g. "Score not resetting on game restart" found during GAL-39) | `bug` | Imperative fix description ("Reset score on game restart") | +| Unresolved blocker after a review loop exhausted its cycle limit (Phase 4 plan review or Phase 8 final review) | `followup` | Reference the `@check` finding | +| `@test` `NOT_TESTABLE` "future seam" notes that imply a real test gap | `tech-debt` | Describe the missing seam | + +**Do NOT file follow-ups for:** +- `@simplify` advisory recommendations the orchestrator chose not to act on — these are records, not missing work; they belong in the run summary. +- Cosmetic / formatting / naming nits. +- Anything already covered by an existing TODO issue (`@pm` lists existing issues; check the title/description before filing a duplicate). + +**Routing rules:** +- Each new issue is a sub-issue (`parent: $ISSUE_ID`). `@pm` will add it to the parent's `## Sub-issues` list automatically. The user can promote it to top-level later if it deserves its own slot. +- Issue body must include a "Discovered during" paragraph naming the run's branch and (where relevant) commit SHA, plus enough context for the user to triage it later without having to re-read the run. +- Status: `Todo`. Default labels per the table; the orchestrator may add additional labels inferred from the parent (e.g. propagate `gameplay` from GAL-39 to a gameplay-relevant follow-up). +- The Run Summary (next subsection) lists each filed follow-up by ID so the user has one place to see them. + +### Commit TODO Changes + +After both the TODO Update and File Follow-ups steps, commit everything under `TODO/` in a single atomic commit: `chore(todo): update status, file follow-ups`. Stage the worked issue file, the dependent index (README.md or parent file), and any newly created follow-up issue files. + +If no follow-ups were filed, the commit message simplifies to `chore(todo): update status and progress` and only the TODO Update changes are staged. ### Run Summary - Write `$RUN_DIR/summary.md` with: - - **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-07T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one. + - **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-08T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one. - Issue reference and title - Branch name and final commit SHA(s) - Summary of implementation - TDD evidence (RED→GREEN per task, NOT_TESTABLE justifications) - Review outcomes (plan review + final review verdicts) - - Unresolved items (if any) + - **Filed follow-ups** — list each new issue created in the File Follow-ups step by ID, title, and reason (`bug` / `followup` / `tech-debt`). If none, write "None." + - **Advisory notes (not filed)** — any `@simplify` or `@check` recommendations the orchestrator chose not to act on and did not turn into a TODO. These are records for the user to consider, not tracked work. - Files changed - **Do not commit anything under `.workflow/`.** The whole directory is per-run, per-branch state. Recommend the user add `.workflow/` to `.gitignore` if not already.