Workflow Improvement — Findings Synthesis (2026-06-12)

Workflow Improvement — Findings Synthesis (2026-06-12)

Session: workflow-improvement (Fable 5). Sources: /insights report + facets/session-meta JSONs (70 sessions, 2026-06-04→12), workflow-machine map (Explore agent), historic-intent reconstruction (Explore agent), ledger audit (inline), external research (web agent, sources cited inline).

1. Usage baseline (9 days, 70 sessions)

• 858 user msgs, ~504 session-hours, 362 commits, +13,475/−776 lines, 244 files.
• Tool calls 6,310: Bash 3,990 (63%), Agent 530, Read 471, Edit 343, Write 143, ToolSearch 134.
• Tokens: 6.77M input (uncached) / 30.9M output.
• Outcomes: 25 fully-achieved, 16 mostly (stalls mostly = awaiting Liam decisions, not failures), 2 partial, 7 unclear.
• Tool error rate 4.6% (288; Command Failed 176).
• Inferred satisfaction: 65 likely-satisfied / 10 satisfied / 2 happy. Helpfulness: 30 very, 13 essential, 4 moderate, 3 unhelpful.

Verdict: the orchestration machine ships. Friction is almost entirely environment plumbing + self-inflicted shell/instruction issues, not logic capability.

2. Friction Pareto (50 facet sessions; 19 buggy_code, 6 wrong_approach, 21 narratives)

#	Cluster	Evidence (≈sessions)
F1	Sandbox/hook write-denials on canonical .claude paths (OQ mailbox, events_dir, skills) → sandbox-disabled workarounds	≥4
F2	Concurrent git contention: watchers recreating index.lock, CWD drift into completing worktrees, stale branches, lost auto-cleaned worktree	≥5
F3	Shell self-inflicted: heredoc !=/history-expansion mangling, unquoted-var false “ALL OK” — recurred AFTER evaluator flagged it	≥3
F4	False exit-0 / unverified completion signals masking test failures	≥2
F5	Ledger CLI latent bugs: char-budget rejections, non-ASCII byte-stability guard, backlog id-reuse collisions (bl-287/288), isolation breach staging in main checkout	≥2
F6	Interactive prompts hanging background shells (supabase db push)	1
F7	Watcher pointed at wrong OQ mailbox path; orphaned watchers	1–2
F8	IP leak near-miss: client name in migration filename (user caught)	1

Meta-finding (this session): the cd-guard hook regex cd /Users/liamj/Documents/development/knowledge-hub prefix-matches knowledge-hub-docs-site → false-positive BLOCKED on a legitimate docs-site cd. Guard hooks themselves are generating friction.

3. Workflow machine (current)

5 roles (Orchestrator main-session + Planner/Executor/Checker/Curator agents), conditional spec chain {N.1–N.4}, per-subtask pipeline: gitnexus impact → TDD → commit+journal → checker audit → curator triage → CLI ledger writes → merge+knip. Full map in session transcript (Explore agent report).

Per-subtask fixed overhead (runs regardless of subtask size): impact analysis, detect-changes, journal block, checker dispatch (spec-slice read + test + lint + JSON verdict), possible curator dispatch, ledger CLI mutations, post-merge status + knip.

12 duplication/vestigial smells across .claude/skills/* + .claude/agents/*: gitnexus discipline ×3 files, KH quality bars ×4, spec-chain structure ×2, dependency constraints ×2, state-machine rules ×4, empirical-verification ×2, Liam-promote rule ×2, Taskmaster disclaimers ×3, escalation rule ×N, friction register ×3, ledger-write phrasing ×2, spec-tier budget ×2. Every dispatch brief carries duplicated tokens; drift risk on every edit.

4. Ledger reality

• Canonical location: docs-site src/content/docs/ledgers/ (task-list.json 3.25MB, backlog 226KB, roadmap 23KB, retros 7.6KB, umbrellas; per-entity dirs tasks/ (96 ID-N.md), backlog/ (186), roadmap/, retros/).
• CLAUDE.md ledger table is stale — points to docs/reference/*.json which no longer exists in code repo. Old copies linger in stale worktrees.
• task-list.json: 96 tasks / 756 subtasks. details journals = 79% of bytes. Done tasks = 78% of bytes. Median task 10KB; top: id-28 249KB, id-68 184KB, id-90 176KB.
• Git: tracked in docs-site, only 5 commits so far (recent move). At ~3.2MB/commit-touch this becomes heavy at current mutation cadence.
• product-retros.json: 1 entry (S264, 2026-05-25) — the structured retro loop exists but isn’t closing. Mempalace diary (38 writes/9 days) is doing the actual memory work.
• ledger-cli.ts mediates writes (id-90 mutex daemon); per CLI there are read/update/create/promote subcommands.

5. Intent vs reality (docs-site archaeology)

• Original kh-sdlc-workflow design: 5 roles + deferred Evaluator; memory-transcript.md proposed Redis-pattern vector-dedup memory — never implemented; superseded de facto by retros ledger + mempalace diary (two unintegrated systems).
• id-92 hardened evaluator (guards, baseline retro-assist); routing to ledger/friction-register exists but output volume ≈ 0 (one ledger entry).
• Unimplemented original promises: Workflow Auditor, Linear migration, Taskmaster feedback loop. Post-hoc additions with no design doc: clash-free protocol, friction register, A1.W wrapper.

6. External research (2026-06; sources in research agent report)

• Anthropic harness patterns (eng blog Nov-25→Mar-26): progress-file + git-log as cross-session memory; initializer + incremental agents; one-feature-at-a-time; smoke-test on session start. C-compiler fleet post: task-level file locks, dedicated dedup/consolidation agent, external oracle for verification, strict output discipline (log to files, return summaries).
• Verification theater is the documented checker failure mode. Mitigations: deterministic checks first; intent-based review against numbered invariants (KH already does); checker emits executable verification script, not prose verdict; per-axis parallel reviewers.
• Subagents = context firewalls (official docs framing): summaries-only returns; KH already mandates bounded results.
• CLAUDE.md guidance: ~100–200 line ceiling; CLAUDE.md orients, skills carry HOW, hooks carry MUST (deterministic enforcement > prose); named anti-patterns: gotcha graveyards, rule duplication across agent files. KH CLAUDE.md = 330 lines + global import.
• RTK (rtk-ai/rtk, v0.42.x, 61.7k★): PreToolUse rewrite of bash to filtered output. Cache-safe (prefix-caching analysis: tool results are appended tokens; trimming doesn’t invalidate). Honest estimate 10–30% on mixed workloads (not 60–90%); caveat: aggressive filtering can hide error detail → conflicts with silent-failure discipline unless audited.
• abtop (graykode/abtop): fleet telemetry TUI; --json snapshot (per-session tokens, context-fill %, child procs, orphaned ports). Monitoring, not evaluation. Cheap watcher input for stalled/saturated workers.
• Ledger shape: field consensus = CLI-mediated, slice-queryable task graphs (Beads: SQLite + append-only JSONL). CLI-mediated monolith is acceptable; pressure point is read cost + git weight → slice reads + compaction before any SQLite move.

7. Other answers to notes-file questions

• Browser-based ledger access (chrome-devtools-axi / cmux): not recommended — CLI slice reads are cheaper and deterministic; browser surfaces cost tokens (snapshots/screenshots) and add nondeterminism. task-view remains the human viewing surface.
• gitignore task-list.json: prefer compaction over gitignore — done-task journal archival (into per-task mirrors) cuts live file ~70–78%; keeps canonical DB in git history. Revisit only if still heavy.
• Sandbox off? No — denials were all legitimate workflow paths (fixable allowlist/carve-outs), and sandbox still guards worst-case writes. Fix config, don’t remove the guardrail.
• Stale worktrees: ~25 prunable agent worktrees + several named ones in .claude/worktrees/ right now (id71-review, id93-id64, subo-id95 look dormant; check git status before removal; subo-id101/s344-id95b may belong to active sessions).

8. Execution log (same session — decisions D1–D6 ratified as recommended)

• WS-A shipped (code commit 083689df6): guard-regex boundary fixes (cd + git-C), sandbox/Tier-2.2 carve-outs for canonical .claude/cmux-events/**, NEW bash-heredoc-preflight.sh + ip-leak-filename-guard.sh hooks (denylist template at docs-site .config/ip-denylist.txt — Liam to populate), watch-fleet oq-state.json channel (SEEN_BLOCKED), worktree prune (~25 cleared; kept id71-review, s344-id95b per Liam; locked id-102 wt). 11/11 synthetic hook tests pass.
• WS-B1/B4 shipped (commit fa6633b67): CLAUDE.md 330→143 lines + nested CLAUDE.mds (__tests__/, components/, supabase/, scripts/, lib/mcp/ append); slice-read mandate across start-session/workflow-orchestration/references; merge-cadence pre-integration preflight.
• WS-B3 shipped (code df1584022, docs-site 5052f56f): 516 journals archived → ledgers/archive/, task-list.json 3.25MB→1.34MB (−59%), mirrors regen OK, regen-mirrors.sh drift-check repo fix.
• WS-B2 dispatched to worktree agent (dedupe 12 smells → shared-discipline.md).
• Mempalace audit (new D-item from Liam): 350,382 drawers; sessions wing 100,693; duplicate knowledge_hub(121,180)/knowledge-hub(75,880) wings; ~90 junk micro-wings; KG 14 entities/7 triples. Purge+selective re-mine recommended; preserve diary (977) + decisions (720). Scheduled next session.
• Continuation prompt: docs-site continuation-prompts/continuation-prompt-kh-s346-workflow-improvement-wsc.md (WS-C, RTK trial, mempalace re-mine).
• Incidental tooling friction observed this session (feed to evaluator): lavish-axi 500s on stale state.json referencing deleted artifact files (workaround: reset state.json); guard hooks block their own test commands (string-literal matching — test via file indirection); prettier pre-commit reformatting of new scripts.