Why TRW
TRW is useful when the expensive part of AI-assisted engineering is no longer generating code, but preserving decisions, resuming work, and proving what actually passed. It makes those records explicit; it does not make every session remember everything automatically.
Start with three evaluation questions
- 01Which project facts are repeatedly rediscovered or contradicted?
- 02Which validation and review evidence should survive the conversation that produced it?
- 03Can a fresh session resume from repository records without trusting stale chat context?
The observable problem
A client or model may already import repository instructions and read source effectively. The gap appears when useful state exists only in a closed conversation or an unsupported completion claim. Look for these failures in your own work rather than assuming a fixed savings estimate.
Rediscovery
A later agent spends time recovering a decision or gotcha that was known but never stored in a searchable project record.
Unverifiable completion
A fluent summary says work passed, but the command, scope, counts, or review receipt are missing.
Interrupted execution
Context compacts or a session ends, leaving no checkpoint that another agent can inspect and resume.
Ambiguous handoff
Multiple contributors return prose instead of explicit ownership, changed paths, dependencies, and integration evidence.
Claim, mechanism, evidence, boundary
Evaluate TRW by the records it can produce, not by a promise that agents become smarter. Each need below has an inspectable mechanism and a limit.
Reuse a project findingInspect
- Mechanism
- Record it with trw_learn; retrieve it through session start or focused recall.
- Evidence
- A stored entry with detail, tags, source context, and an explicit recall result.
- Boundary
- Recall returns a candidate to verify. It does not prove universal task improvement.
Resume interrupted workInspect
- Mechanism
- Create a run and checkpoint meaningful milestones.
- Evidence
- Active-run state and the latest checkpoint under .trw/runs/.
- Boundary
- The checkpoint can be stale; compare it with current source before continuing.
Make completion inspectableInspect
- Mechanism
- Run project-native checks, then record their real outcome with trw_build_check.
- Evidence
- Command output plus scope, counts, failures, coverage when measured, and static-check state.
- Boundary
- The receipt is caller-reported. TRW records checks; it does not execute them.
Apply a hard delivery policyInspect
- Mechanism
- Evaluate task type and recorded evidence at trw_deliver.
- Evidence
- A passing receipt, structured acceptable-failure record, or authorized override.
- Boundary
- Phase guidance and optional hooks are not substitutes for the server-side gate.
| Need | Mechanism | Evidence | Boundary |
|---|---|---|---|
| Reuse a project finding | Record it with trw_learn; retrieve it through session start or focused recall. | A stored entry with detail, tags, source context, and an explicit recall result. | Recall returns a candidate to verify. It does not prove universal task improvement. |
| Resume interrupted work | Create a run and checkpoint meaningful milestones. | Active-run state and the latest checkpoint under .trw/runs/. | The checkpoint can be stale; compare it with current source before continuing. |
| Make completion inspectable | Run project-native checks, then record their real outcome with trw_build_check. | Command output plus scope, counts, failures, coverage when measured, and static-check state. | The receipt is caller-reported. TRW records checks; it does not execute them. |
| Apply a hard delivery policy | Evaluate task type and recorded evidence at trw_deliver. | A passing receipt, structured acceptable-failure record, or authorized override. | Phase guidance and optional hooks are not substitutes for the server-side gate. |
Evidence order
When speed and certainty compete, use this order to decide what must survive the handoff.
1. Current truth
Read the live repository and report skipped, failed, partial, or unverified work explicitly.
2. Project-native proof
Prefer the repository’s commands, artifacts, and acceptance criteria over a plausible narrative.
3. Reusable records
Preserve only findings and handoffs that a later agent can inspect, verify, update, or retire.
4. Proportionate process
Use the smallest ceremony tier that still includes the evidence the task’s risk requires.
Product boundaries
Not a model or IDE
TRW works above supported coding clients. It does not generate code or replace the editor and model you choose.
Not automatic conversation memory
Agents explicitly record and recall selected state. Chat content is not silently promoted into future instructions.
Not a test runner
Your project runs its own tests, build, lint, and type checks. TRW records the supplied result and evaluates policy.
Not an unconditional zero-egress guarantee
Project memory is local by default, and memory_local_only=true denies memory network access. Auth, downloads, hosted features, or explicitly invoked network tools have separate boundaries.
Run a project evaluation
Choose one active repository and compare similar work before and after adoption. Define the observation window by enough repeated tasks to expose the problem; do not assume a universal setup time or payback date.
RediscoveryInspect
- Baseline
- Count repeated explanations or re-solved gotchas in comparable tasks.
- Useful signal
- A relevant stored record is recalled and verified before the work repeats.
RecoveryInspect
- Baseline
- Interrupt a real multi-step task at a natural milestone.
- Useful signal
- A new session can explain and resume the checkpoint from current source.
Claim accuracyInspect
- Baseline
- Compare completion summaries with CI and review evidence.
- Useful signal
- Recorded scope and outcomes match the authoritative project checks.
Operating costInspect
- Baseline
- Measure the calls, review effort, and maintenance your team actually adds.
- Useful signal
- Recovered context or avoided rework is worth the observed process overhead.
| Measure | Baseline | Useful signal |
|---|---|---|
| Rediscovery | Count repeated explanations or re-solved gotchas in comparable tasks. | A relevant stored record is recalled and verified before the work repeats. |
| Recovery | Interrupt a real multi-step task at a natural milestone. | A new session can explain and resume the checkpoint from current source. |
| Claim accuracy | Compare completion summaries with CI and review evidence. | Recorded scope and outcomes match the authoritative project checks. |
| Operating cost | Measure the calls, review effort, and maintenance your team actually adds. | Recovered context or avoided rework is worth the observed process overhead. |
When to skip it
Throwaway work
If no later session will reuse the code or evidence, durable project records add little value.
No recurring context
A small uniform project may not have enough non-obvious decisions or interruptions to justify another layer.
No willingness to record evidence
Optional hooks cannot create trustworthy receipts on their own. If nobody will record real outcomes, the framework becomes decorative.
Incompatible repository policy
If project-local .trw state or the required client integration is prohibited, resolve that operating constraint first.