trace-first-starter

TS — TFW-25: Values & Principles Consolidation

Date: 2026-04-04 Author: Coordinator (AI) Status: 🟡 TS_DRAFT HL: HL-TFW-25 RES: RES-TFW-25

Scope

Phase A only (“Audit & Consolidate”). Phase B deferred.

Files in scope (7):

  1. .tfw/README.md — §Values and Principles rewrite
  2. KNOWLEDGE.md — §0, §3, §4, §5 changes
  3. knowledge/convention.md — prune 6 facts
  4. knowledge/process.md — prune 5 facts
  5. knowledge/philosophy.md — compress F4 (will be in README values)
  6. .tfw/conventions.md — absorb P10-P13 content into existing §11 or new subsection
  7. README.md task board — status update

Budget: 7 files (= max). 0 new files. ~200 LOC net reduction.

Step 1: .tfw/README.md §Values and Principles

Replace lines 217-242 with 8 values in narrative format.

Target content (exact text to write):

## Values and Principles

### Traces Over Code

The trace is the product — intent, decisions, constraints, and alternatives matter more than the implementation itself. A codebase without traces is a black box. TFW captures not just *what* was built, but *why*, *what else was considered*, and *what was rejected*.

### Candor Over Flattery

AI agents trained on human feedback develop a habit of agreeing with users and praising their ideas. TFW agents are explicitly instructed: **Don't be sycophantic.** Be direct, precise, concrete. Flag risks. Disagree when evidence supports it. The coordinator's job is to ask uncomfortable questions and catch implicit assumptions — quality of planning matters more than speed of pipeline progression.

### Completeness Over Speed

When asked to implement, provide complete, usable output. **No placeholders.** No `// TODO: implement this`. If you can't produce a complete solution, say what's missing — don't fill the gap with a stub.

### Honesty Over Convincingness

AI agents that sound confident while being wrong are more dangerous than agents that refuse to answer. TFW agents must never fabricate data, claim untested results, or simulate external systems. When context is insufficient, the correct behavior is to ask, not guess. Confidence without correctness is the deadliest failure mode.

### Structural Enforcement

Gates should be structural — file existence, folder structure, required artifacts — not procedural (checkboxes in documents, state tables in headers). If a stage isn't done, the file doesn't exist. No parsing needed, no format compliance required, no update discipline to enforce. The filesystem is the state machine.

### Naming Creates Behavior

Right terminology triggers right associations in AI agents. A small prompt with precise terms is more effective than a long prompt with explanations. TFW adopted OODA, Sufficiency Verdict, Trust Protocol, Progressive Disclosure — each term replaced paragraphs of instructions. If you have to explain what a step does, the step is named wrong.

### Single Source of Truth

`.tfw/` contains exactly one copy of each convention, template, and workflow. Tool adapters reference it, never duplicate. If you need to change a rule, change it in one place.

### Portability

Everything is Markdown. No vendor lock-in. The files work in Obsidian, VS Code, GitHub, or a plain text editor. The knowledge belongs to you, not to a platform.

Step 2: KNOWLEDGE.md §0 — Prune to 7 principles

Replace lines 8-26 (current 14 P# entries) with 7 entries.

P# items to REMOVE (6):

P# item to PROMOTE to README (1):

Surviving §0 (7 items, compressed to 1-liners):

## 0. Philosophy & Principles

| # | Principle | Source |
|---|-----------|--------|
| P1 | Traces over code — intent, decisions, constraints matter more than implementation | `.tfw/README.md` §Values |
| P2 | Index, don't duplicate — link to sources, don't copy | TFW-5 HL §7 |
| P3 | Philosophy stays rich — if DRY conflicts with narrative value, narrative wins | TFW-4 HL §7.1 |
| P5 | Meta-project awareness — this repo describes TFW AND uses TFW, overlap is by design | TFW-4 HL §7.3 |
| P7 | Self-review is not review — execution and review must be separate role-locked acts | TFW-8 HL §7 |
| P8 | Research ≠ passive checklist — external tools, pointed questions, WAIT gates. See `research/base.md` | TFW-11/14/17 |
| P9 | Coordinator quality > speed — uncomfortable questions, implicit assumptions, anti-rush. See `plan.md` Mindset | TFW-17 HL §7.1 |

Note: P# numbering preserved (P4, P6, P10-P14 become gaps). Historical task HL refs to removed P# remain valid as source links.

Step 3: KNOWLEDGE.md §3 — Prune Legacy

Remove 18 resolved items from lines 115-137 (all pre-TFW-22, fully superseded).

Keep lines 138-148 (TFW-22 through TFW-24 items: 11 items).

Lines to REMOVE:

Step 4: KNOWLEDGE.md §4 — Remove entirely

Delete lines 152-160 (Tech Stack & Infrastructure section). Trivially obvious from repo.

Step 5: KNOWLEDGE.md §5 — Update fact counts

Update the Project Facts index table to reflect new counts after Step 6-7:

Step 6: knowledge/convention.md — Prune 6 facts

Remove:

Keep: F1, F2, F3, F5, F7, F11 (6 facts)

Renumber F5→F4, F7→F5, F11→F6 for clean sequence.

Step 7: knowledge/process.md — Prune 5 facts

Remove:

Keep: F1, F4, F5, F6, F7 (5 facts)

Renumber for clean sequence.

Step 8: .tfw/conventions.md — Absorb P10-P13

Add subsection to §11 or create §11.1 “Design Rules” with compressed P10-P13 content:

### Design Rules (from P10-P13)

- **Token density**: workflow instructions ≤1200 words. Templates own format; workflows reference templates
- **Inline enforcement**: enforcement-critical values MUST be inline (Pattern A: defaults + config key). Pure refs (Pattern B) = broken
- **DNA/Library**: Role Lock + Mindset = always inline. Reference data = via ref-inside-step. Step self-contained, ref adds precision
- **Progressive Disclosure**: agent loads only what it needs now. Mode files loaded at Step 2, not at start

Placement decision: After reviewing conventions.md structure, insert into existing §11 (Scope Budgets) if it covers “design constraints”, OR create a new subsection nearby. Executor decides exact position.

Step 9: README.md task board — Update status

Change TFW-25 status from 📝 HL_DRAFT to 🟢 RF after execution complete.

Acceptance Criteria

*TS — TFW-25: Values & Principles Consolidation 2026-04-04*
This site is open source. Improve this page.