pal-e-docs

Convention: TODO Lifecycle

convention-todo-lifecycle Convention

active convention
Project

Convention: TODO Lifecycle

Principle

Work items are either plan phases (strategic, auto-sync to board) or typed Forgejo issues (tactical, added to board). There are no standalone todo-* or bug-* notes in pal-e-docs. The "todo" column on the kanban board is a status (scoped, awaiting Lucas's review), not a work type. Discovered work becomes a typed Forgejo issue immediately — the issue is the spec.

Four Issue Types

Every Forgejo issue includes a ### Type header that determines which template is validated against:
Type Template When to Use Key Sections
<strong>Feature</strong> <code>template-issue-feature</code> New functionality, enhancements, planned work User Story, File Targets, Test Expectations, Constraints
<strong>Bug</strong> <code>template-issue-bug</code> Broken behavior, regressions, alert-driven fixes What Broke, Repro Steps, Expected Behavior, Environment
<strong>Spike</strong> <code>template-issue-spike</code> Unclear scope, needs investigation, time-boxed Question, What to Explore, Success Criteria, Time-box
<strong>Nit-Bundle</strong> <code>template-issue-nit-bundle</code> QA nits from an approved PR, bundled for triage Source, Original Work, Nits, Segmentation Notes
If no ### Type header is present, validation defaults to Feature (backward compatible).

Type Decision Tree

  • Is something broken that used to work? → Bug
  • Do we know what to build/change? → Feature
  • Do we need to investigate before scoping? → Spike
  • Is this housekeeping, docs, or config with no code file targets? → Task
  • Are these QA nits from an approved PR? → Nit-Bundle

Lifecycle

Stage State Where it lives
1. Discovery Work identified during session (bug, improvement, feature, task) Verbal or noted in session context
2. Decision gate Betty Sue types the work (Bug/Feature/Spike/Task) and creates a Forgejo issue. Betty Sue decides
3. Board entry Typed Forgejo issue created. Added to project board at <code>backlog</code> or <code>todo</code>. Forgejo + project board
4. Review gate Item sits in <code>todo</code> column. Lucas reviews scope, acceptance criteria, technical approach. Project board
5. Dispatch Lucas approves → item moves to <code>next_up</code>. Agent spawned (Feature/Bug) or investigation begins (Spike). Project board + Forgejo

Rules

  • No todo-* or bug-* notes. Work items are plan phases or typed Forgejo issues. The check-note-template.sh hook blocks creation of notes with todo or bug note_type. Existing legacy notes should be migrated over time.
  • Three types, same destination. Bugs, features, and spikes all flow through the same board. The type determines the template (validation) and the expected output (code vs knowledge).
  • Two paths, same board. Foundational/architectural work (new capabilities, cross-repo, changes architecture diagrams) → phase in the plan. Tactical work (improvements, bugs, features on mature projects) → Forgejo issue on the board. The decision gate: would this change an architecture diagram? If yes → phase. If no → issue.
  • The todo column is a review gate. Items in todo are scoped and awaiting Lucas's review. This creates peer review on planning, mirroring PR review on code. Only after review do items advance to next_up.
  • Once in the plan, it's a phase. Work items in the plan are phases or subphases, never TODOs. If it has a scope, a goal, and a place in the sequence — it's a phase.
  • Forgejo issues auto-sync to boards. Open issues from linked repos appear on the board via sync-issues. No manual board item creation needed for synced repos.

Triage Checklist

  • Is this architectural (changes a diagram)? → Create a plan phase or subphase.
  • Is something broken? → Create a Bug Forgejo issue.
  • Is scope unclear, needs investigation? → Create a Spike Forgejo issue.
  • Is this a new feature or enhancement? → Create a Feature Forgejo issue.
  • Are these QA nits from an approved PR? → Create a Nit-Bundle Forgejo issue (one per PR, bundled).
  • Is it small enough to absorb into an existing phase's scope? → Add it to that phase's scope section.
  • Is it no longer relevant? → Close the Forgejo issue as won't-fix, or skip creating one.

Query Pattern

Items in backlog are the intake queue. Items in todo are scoped and awaiting Lucas's review. The board is the single view of all work status.
  • template-issue-feature — Feature issue template
  • template-issue-bug — Bug issue template
  • template-issue-spike — Spike issue template
  • template-issue — canonical issue-as-spec design principle
  • template-project-page — Inbox section surfaces untriaged items
  • convention-subphase — how subphases work under phases