Write Task Todo

Write Task Todo

Use this skill after analyze-task and after the analysis has been discussed and aligned when a task is large enough to need multiple implementation loops, commits, reviews, or cross-layer coordination.

This skill turns an analysis result into a single working task document:

• docs/todolist.md

Purpose

Create a todo that is:

• structured
• execution-friendly
• test-aware
• biased toward definitions and interfaces before UI

This skill is not for coding and not for long-form design writing.

Preflight gate for large cross-layer tasks

Before writing docs/todolist.md, use a short Decision Draft when the task crosses any of these Formax boundaries:

• permissions / policy / approval / hooks
• runtime config / persistent settings / credentials / secrets
• tool runtime / prompt exposure / deferred exposure / ToolSearch
• SDK / REPL / app-server / Web / Electron entrypoints
• protocol boundaries, child processes, startup timing, session lifecycle, result mapping, files, binary payloads, or cleanup

Do not write the final todo until the Decision Draft is aligned. The draft should be short and must answer:

• Storage and config source: where data lives, who reads it, and who must not read it.
• Schema and strictness: accepted fields, rejected fields, default values, and unknown-field behavior.
• Startup / activation timing: which entrypoint may create side effects and which phases are pure.
• Permission model: whether existing Formax permission / approval / hook flow can express the behavior before adding new actions.
• Capability level: whether the feature is a tool, slash command, SDK control, hook, transcript renderer, config setting, or prompt exposure behavior.
• Entrypoints: REPL, SDK, app-server, Web, and Electron behavior.
• Result / IO boundaries: output caps, file locations, binary/media handling, cleanup, secrets, and timeout behavior.
• Non-goals: what is explicitly out of Phase 1 and what user-visible behavior that implies.

For small single-layer fixes, skip the Decision Draft and keep the todo lightweight.

Core rules

1. Use a single working todo file

   • default path: docs/todolist.md

2. Do not create a parallel source-of-truth doc at the start

   • put evolving definitions in the todo first
   • once a concept becomes stable and long-lived, promote that part into the repo's canonical docs
   • in Formax, canonical docs usually mean docs/contracts/*, docs/frontend/*, docs/environment-variables.md, or tightly owned package-local README deep dives
   • after promotion, the todo should reference the canonical doc rather than maintain a second truth

3. Prefer definitions before implementation

   • canonical-doc impact
   • data model
   • types / interfaces
   • tests
   • then implementation layers

4. Use [x] and [ ] strictly

   • [x] only for confirmed facts, fixed decisions, or completed work
   • [ ] for pending work
   • never mark assumptions as [x]

5. The todo must be loop-ready

   • break work into mainline slices that can be implemented, verified, reviewed, and committed independently
   • every meaningful implementation loop should include an explicit unchecked codex review item
   • every meaningful implementation loop should include a Loop Contract that says what review may block on and what must be classified as later-loop/non-blocking
   • use the repository's existing review profile instead of redefining model, reasoning, or timeout in the todo

6. If the task is too small to justify a todo

   • say so explicitly
   • do not create docs/todolist.md

7. Do not generate a todo while key alignment questions are still unresolved

   • if scope, semantics, host/scope boundaries, or architecture direction are still under discussion, stop and ask for alignment first

8. Add a spec lock / review-scope lock for high-risk multi-loop work

   • required when the task crosses multiple layers such as shared semantics, app-server protocol, session persistence, runtime config/profile, credentials/secrets, startup/recovery, Electron/Web bridge, or Web UI state
   • required when review is likely to confuse final-feature completeness with the current implementation slice
   • include a semantic decision table and a review finding triage policy before implementation loops
   • create a dedicated review findings log when the task is large enough to expect multiple codex review runs
   • do not let the todo imply that review findings are direct edit commands; findings must be classified before code changes

9. Add an EntryPoint Matrix for cross-entrypoint features

   • required when behavior may differ across REPL, SDK, app-server, Web, or Electron
   • each relevant entrypoint must say whether it reads config, starts/activates runtime, exposes the capability, renders UI/transcript state, and has tests
   • if an entrypoint is explicitly out of scope, say what it does instead, such as empty overlay, unsupported error, no-op with diagnostic, or no surface

10. Attribute critical semantic decisions

    • mark each non-obvious rule as one of:
      • Reference-derived with the concrete reference, such as Claude Code, OpenAI SDK, MCP SDK/spec, or another repo source
      • Formax-existing for behavior inherited from current contracts/code
      • Formax-Phase-1 safety choice for thresholds, fail-closed defaults, local caps, cleanup, or bounded behavior we choose ourselves
      • User-aligned for decisions explicitly settled with the user
    • do not label a rule as parity/reference behavior unless the source was actually checked

11. Prefer existing Formax models before inventing new concepts

    • for permissions, first test whether existing permission / policy / approval / hook flow can express the behavior
    • for tools, first decide the product level: normal tool, dynamic tool, ToolSearch/deferred catalog behavior, slash command, SDK control, or renderer
    • add new policy actions, protocol fields, brokers, registries, or config files only after documenting why existing Formax contracts cannot express the need

12. Make non-goals actionable

    • for large protocol/runtime/config tasks, a non-goal should say:
      • whether the upstream/reference system has the capability
      • whether Formax Phase 1 implements it
      • what behavior the user sees in Phase 1
    • avoid vague non-goals such as "defer X" without the resulting behavior

13. Run a vague-language scan before finalizing the todo

    • search for terms like where needed, if needed, if practical, either, or explicitly, fallback, unless scoped, later, may, might, optional, as needed, TBD, unresolved
    • every hit must become one of:
      • a Phase 1 accepted rule
      • an explicit non-goal
      • a Phase 2 backlog item
      • a stop condition
      • a question for the user
    • do not leave implementation-time choices hidden in prose

14. Source thresholds and IO bounds

    • any output cap, timeout, byte limit, file-backed path, cleanup policy, binary/media behavior, or secret redaction rule must cite its source
    • if the value is a Formax local safety choice, say that explicitly and add tests that pin the behavior