Tech Debt Registry¶
| # | Source | Severity | File(s) | Description | Status |
|---|---|---|---|---|---|
| TD-33 | TFW-14 RES obs. | Low | .tfw/workflows/handoff.md, adapters |
tfw-handoff misnaming — no handoff status/document exists. Consider renaming to tfw-execute. Low priority, high blast radius |
✅ Closed (cost/benefit: no agent confusion, high blast radius, low value) |
| TD-45 | TFW-18 RF obs. #1 | Low | .tfw/conventions.md |
§10.1 and §10.2 subsection numbering breaks the flat numbering scheme (§1-§15). Future renumbering pass needed | ⬜ Backlog |
| TD-59 | TFW-23 REVIEW FC#1 | High | .tfw/workflows/ |
No crash-recovery gate mechanism — after session crash, WAIT gates are lost. Need "Gate Recovery" protocol | ✅ Closed (file-based state machine pattern in research D31 + review D41 covers critical paths) |
| TD-63 | TFW-25 RF obs. #1 | Med | KNOWLEDGE.md L39-75 |
§1 Architecture Decisions table (D1-D46) = 46 rows with long rationale text. Main driver of KNOWLEDGE.md exceeding 120-line target. Consider compression or active/archived split | ⬜ Backlog |
| TD-73 | TFW-26/B RF obs. #6 | Med | docs/requirements.txt |
MkDocs 2.0 will break mkdocs-gen-files plugin. Pin or monitor | ⬜ Monitor |
| TD-79 | TFW-27/B RF obs. #1 | Med | docs/scripts/gen_docs.py |
gen_docs.py at 692 LOC — exceeds 600 LOC threshold. resolve_references() (200+ LOC) extraction candidate → resolvers.py |
⬜ Backlog |
| TD-80 | TFW-27/B RF obs. #2 | Med | docs/scripts/gen_docs.py |
Artifact resolver doesn't search PhaseX subfolders for RF [TFW-26](../tasks/TFW-26__documentation_site/HL-TFW-26__documentation_site.md). Many "Unresolved reference" info messages. Needs thorough fix |
⬜ Backlog (important) |
| TD-81 | TFW-27/B RF obs. #3 | Med | docs/scripts/gen_docs.py, README.md |
_generate_tasks_index() Task Board parser is fragile — regex-based parsing of README.md tables |
⬜ Backlog |
| TD-82 | TFW-27/B REVIEW | Low | docs/mkdocs.yml |
attr_list and md_in_html extensions added for README logo — may be removable if README format changes |
⬜ Backlog |
| TD-88 | TFW-32/A REVIEW obs. #1 | Low | KNOWLEDGE.md L37 |
§1 Architecture Map says "Updated via tfw-docs workflow" — correct, but "optional" annotation could be clarified after docs/knowledge separation |
⬜ Backlog |
| TD-90 | TFW-32/C RF obs. #2 | Low | .tfw/workflows/plan.md |
plan.md grew from 108 to ~150 lines after TFW-32/C + TFW-38/B. Still within workflow word limit but approaching threshold. Monitor growth | ⬜ Monitor |
| TD-91 | TFW-32/D RF obs. #1 | Low | README.md L31-36 |
"Who This Is For" bullets lack inline links to specific TFW features — reader can't explore further | ⬜ Backlog |
| TD-99 | TFW-38 Phase B redesign | Med | KNOWLEDGE.md, templates, workflows, glossary, conventions |
KNOWLEDGE.md naming: "knowledge" = ambiguous (file vs concept vs folder). Consider renaming root file to DOCS.md or PROJECT_INDEX.md to distinguish from knowledge/ folder. High blast radius (20+ references). Requires dedicated task |
⬜ Backlog |
| TD-102 | TFW-40/A RF obs. #1 | Low | .tfw/workflows/init.md |
Phase 2 step 1 (create config from template) and Phase 4 step 6 ("Update PROJECT_CONFIG.yaml — finalize all values") overlap after Phase A changes. Phase 4 step 6 should be clarified to "update framework-section values if needed" | ⬜ Backlog |
| TD-103 | TFW-40/B RF obs. #3 | Low | .tfw/project_config.yaml |
Live config file has different comment formatting than template (shorter comment). Pre-existing discrepancy, not introduced by Phase B rename | ⬜ Backlog |
| TD-104 | TFW-40 HL §11 S4 | Med | TFW-16 (backlog) | tfw-doctor (TFW-16) = self-diagnosis of TFW meta-state. User use case: «помочь перепроверять самого себя и починить мета информацию». Concrete trigger: verify knowledge_state.yaml values match project reality after tfw-update | ⬜ Backlog (linked to TFW-16) |
| TD-105 | TFW-41/A REVIEW obs. #2 | Low | .tfw/workflows/handoff.md, .tfw/workflows/plan.md, .tfw/workflows/review.md |
Phase A renumbered TS sections (AC→§5, Technical Guidance→§6, DoF→§7, Cross-Phase→§9). Workflow files may contain hardcoded section numbers referencing old structure. Phase B is assigned to update workflows — this item tracks residual risk if Phase B misses specific references. Verify: grep for §4, §5 Acceptance, Detailed Steps in workflow files. |
✅ Closed (RF TFW-41/B §4: scan confirmed no stale references in any of the 3 workflow files) |
| TD-106 | TFW-41/B REVIEW obs. #1 | Low | .tfw/workflows/review.md |
review.md had a pre-existing "Step 0: Select Review Mode" — the only TFW workflow with a non-standard Step 0. Any future executor inserting a Step 0 will face the same renumbering conflict. Consider adding a comment: "Step 0 is reserved for Session Naming; Select Review Mode is Step 1 by design." |
⬜ Backlog |
| TD-107 | TFW-41/B REVIEW obs. #2 | Low | .tfw/workflows/plan.md |
Multi-phase branch uses alpha-numeric step labels (3b, 4b, 5b…). Any future insertion requires cascade renumbering. Consider replacing with prose-named steps to avoid position-dependent labels. | ⬜ Backlog |
| TD-108 | TFW-41/C REVIEW obs. #1 | Low | .tfw/templates/research/briefing.md |
Briefing template has no forward reference to the ## Dimensions section added to gather.md. A researcher reading only briefing.md before Gather won't know to prepare dimension decomposition in advance. Consider adding: "Identify candidate dimensions (decision factors) before Gather if obvious from briefing." |
✅ Closed (acknowledged in Phase D scope but deferred; logged as TD-109 with updated status) |
| TD-109 | RF TFW-41/D §5 obs. #1 | Low | .tfw/templates/research/briefing.md |
Briefing template has no forward reference to ## Dimensions in gather.md. A researcher preparing only from briefing.md before Gather won't know to pre-identify candidate dimensions. |
✅ Closed (added parenthetical hint to Research Plan field in briefing.md immediately after Phase D review) |
| TD-110 | REVIEW TFW-41/D verify V3 | Low | .agent/workflows/tfw-plan.md |
Line 109: adapter contains >= (ASCII) where source plan.md uses ≥ (Unicode U+2265). 1-byte encoding normalization artifact from copy operation. Semantically identical. Future adapter sync tooling should use byte-copy to prevent recurrence. |
✅ Closed (fixed >= → ≥ immediately after Phase D review) |
| TD-111 | RF TFW-42/A obs. #1 | Med | .tfw/compilable_contract.md (L56, L78) |
References PhaseA/ in resolution rules — will break on kebab-case convention adopted in TFW-42 |
✅ Closed (fixed in TFW-46 KNW: PhaseA/ → phase-a/ in L56, L78) |
| TD-112 | RF TFW-42/A obs. #2 | Med | .tfw/workflows/handoff.md (L140-141) |
Multi-Phase Task Flow example uses HL__PhaseA, TS__PhaseA, RF__PhaseA — needs kebab-case update |
✅ Closed (fixed in TFW-46 KNW: HL__PhaseA → TS__phase-a etc., also removed stale HL__Phase refs — coordinator no longer writes per-phase HLs) |
| TD-113 | RF TFW-42/A obs. #3 | Med | .tfw/workflows/plan.md (L134-136) |
Multi-phase structure example uses PhaseA/, HL__PhaseA__, TS__PhaseA__ — needs kebab-case update |
✅ Closed (fixed in RF TFW-42/B — plan.md Step 7 now uses phase-a/, phase-b/) |
| TD-114 | RF TFW-42/A obs. #4 | Med | .tfw/workflows/research/base.md (L53) |
References research/briefing.md and researchN/briefing.md — needs update to research/iterN/1_briefing.md |
✅ Closed (fixed in RF TFW-42/B — all references now research/iterN/1_briefing.md) |
| TD-115 | RF TFW-43 obs. #1 | Low | .tfw/conventions.md (L152) |
Stage file format reference doesn't mention Mindset blocks as a characteristic of research stage templates. Templates are self-documenting, but conventions text could note this (parallel to review templates description at L195) | ⬜ Backlog |
| TD-116 | REVIEW TFW-46/A V3 | Low | .tfw/templates/RF.md (L68) |
Stale internal cross-ref: §5 Observations should be §6 Observations in §7 FC instruction blockquote. Same block has correct §8 Strategic Insights on L69 |
✅ Closed (fixed in RF TFW-46/B AC-5) |
| TD-117 | RF TFW-46/A obs. #1 | Low | .tfw/compilable_contract.md (L69) |
Pre-existing: REVIEW.md §5 FC Source column should be §7 FC Source column (REVIEW §5 = Tech Debt, §7 = Fact Candidates) |
✅ Closed (fixed in TFW-46 KNW: §5 FC → §7 FC) |
| TD-118 | RF TFW-46/A obs. #2 | Low | .tfw/glossary.md (L48) |
Stale after RF renumbering: RF §7 "Strategic Insights (Execution)" should be RF §8 |
✅ Closed (fixed in RF TFW-46/C — glossary now reads RF §8) |
| TD-119 | RF TFW-46/B obs. #1 | Low | .tfw/workflows/plan.md (L130) | Sub-step numbering mix in Step 7: budget=2, evidence=3, then 3a for TS writing. Pre-existing pattern (see also TD-107) | ⬜ Backlog |
| TD-120 | RF TFW-47/A obs. #1 | Low | .tfw/compilable_contract.md | Source Manifest doesn't include EV template path (evidence/EV.md). EV not in compilation source list | ⬜ Backlog (→ Phase D or next task) |
| TD-121 | RF TFW-47/A obs. #2 | Low | .tfw/project_config.yaml | tfw.templates section doesn't list EV template. Consistent with research templates not listed — convention, not bug | ⬜ Backlog |
| TD-122 | RF TFW-47/B obs. #1 | Low | ~/.codex/skills/tfw-* | User-level TFW skills duplicate repo-local skills in Codex menu. Disable after verifying other repos | ⬜ Backlog |
| TD-123 | RF TFW-47/B obs. #2 | Med | .claude/commands/tfw-task.md, .agent/workflows/tfw-task.md | Non-canonical tfw-task adapters contain stale instructions. Cross-adapter cleanup needed | ⬜ Backlog |
| TD-124 | RF TFW-47/B obs. #3 | Low | iter2/RES.md, HL §10 | Historical traces say $tfw-* is primary. Superseded by Phase B live evidence (/tfw-*). Decide: annotate or preserve as history | ⬜ Backlog |
Added by REVIEW files during task lifecycle. See
.tfw/workflows/docs.md. Closed items purged 2026-04-15 (41 items removed: TD-12..TD-101 with ✅ status).