Lifecycle phases

Two rules to remember

Phase overview

Skim this table first. Then read the phase sections below when you want the mechanics and examples.

Research

trw_session_start()
# -> Loaded 47 learnings (12 high-impact)
# -> Recovered active run: sprint-52-auth-refactor

trw_recall("rate limiting middleware")
# -> 3 relevant learnings found

Exit criteria: Findings registered, relevant learnings loaded.

Plan

trw_init("auth-middleware-refactor")
# -> Run created: .trw/runs/auth-middleware-refactor/
# -> Phase: PLAN

Exit criteria: Plan recorded and ready for implementation.

Implement

# ... write code ...

trw_checkpoint("rate limiter middleware complete, tests next")
# -> Checkpoint saved: 3/5 tasks done

# ... write more code ...

trw_checkpoint("all middleware tests passing")
# -> Checkpoint saved: 5/5 tasks done

Exit criteria: Code written, checkpoints saved.

Validate

pytest tests/ && mypy src/
# -> validation commands pass locally
trw_build_check(
  tests_passed=True,
  test_count=247,
  failure_count=0,
  static_checks_clean=True,
  coverage_pct=94,
  scope="full",
)
# -> recorded evidence: 247 passed, 0 failed
# -> static checks: clean
# -> coverage: 94%

Exit criteria: Build passes, coverage met.

Review

trw_review(
  findings=[{
    "category": "maintainability",
    "severity": "medium",
    "description": "Duplicated validation logic in auth.py and api_keys.py",
  }],
  review_completed=True,
)
# -> substantive manual review recorded with 1 finding

trw_learn(
  "auth validation helpers should be shared",
  "Both auth.py and api_keys.py independently validate API key format..."
)
# -> Learning recorded (impact: 0.7)

Exit criteria: Review passes or issues resolved.

Deliver

trw_deliver()
# -> Build gate: PASS (247 tests, mypy clean)
# -> Delivery state persisted
# -> Run closed: auth-middleware-refactor

Exit criteria: Learnings persisted, run closed.

Adaptive ceremony

Not every task needs all six phases. TRW scores task complexity and assigns a ceremony tier. Bounded fixes use a smaller phase set. Architecture and other high-risk changes use the complete lifecycle. The system scales process to match the risk of the change.

TRW classifies the tier from scope, novelty, cross-cutting or architectural impact, external integrations, refactor depth, and explicit security, migration, or unfamiliar-code risk.

Bounded fix vs comprehensive change

A genuinely bounded fix can begin at implementation. Architecture, cross-package, and other high-risk changes use all six phases. Scope and risk decide the workflow, not whether the request is labeled a feature or a fix.

trw_session_start()
# load prior context

# -> fix the bug
pytest tests/test_target.py
trw_build_check(tests_passed=True, test_count=1, failure_count=0, scope="targeted")
trw_deliver()
# minimal ceremony: implement -> validate -> deliver

trw_session_start()   # Research
trw_recall("auth")
trw_init("feature")   # Plan
trw_checkpoint(...)    # Implement
trw_build_check(tests_passed=True, test_count=247, failure_count=0, scope="full") # Validate
trw_review(findings=[...], review_completed=True) # Review actual diff
trw_learn(...)
trw_deliver()          # Deliver

Phase reversion

Phases are not strictly linear. When later evidence reveals a problem, return to the earlier phase that can resolve it instead of narrating progress past the failure.

• Validate fails - revert to Implement. Fix the code, then re-validate.
• Review finds design issues - revert to Plan. Rethink the approach, then re-implement.
• Implementation hits unknowns - revert to Research. Gather more context, then re-plan.

Hooks

Hooks are optional client adapters. When a client exposes compatible events, they can add reminders, checkpoints, or bounded blocking; correctness remains in TRW tools and middleware when no hook fires.

• Session start - may prompt or invoke startup behavior when the client exposes a compatible event
• Pre-compaction - can request a checkpoint on clients that expose a pre-compaction event
• Phase gates - surface discipline warnings; strict blocking is configuration- and adapter-dependent
• Session end - can warn when delivery was skipped; the MCP delivery tool remains canonical

Where to go next

Continue into requirements if you want the spec layer that sits immediately after workflow understanding. Continue into tools and hooks if you want the mechanics that make those phase boundaries real in day-to-day use.