diff --git a/docs/reports/workflow_markdown_audit_20260608.md b/docs/reports/workflow_markdown_audit_20260608.md new file mode 100644 index 00000000..62fd79e9 --- /dev/null +++ b/docs/reports/workflow_markdown_audit_20260608.md @@ -0,0 +1,367 @@ +# Workflow/Agent Markdown Audit — 2026-06-08 + +**Question source:** end-of-session user prompt — "based on everything done in this session, is there anything in our workflow or agent related markdown that should be updated or introduced?" + +**Author:** Tier 1 Orchestrator (audit; no committed changes) +**Date:** 2026-06-08 +**Status:** Audit only; the 10 recommendations below are NOT yet applied to any file. The user picks which to act on, which to defer, which to discard. + +> **Method.** I read all the workflow/agent markdown in scope (AGENTS.md, CLAUDE.md, GEMINI.md, all 5 `.agents/skills/*/SKILL.md`, the 4 `.agents/agents/*.md`, `conductor/workflow.md`, `conductor/product.md`, `conductor/product-guidelines.md`, `conductor/tech-stack.md`, `conductor/index.md`, `conductor/tracks.md`, `conductor/edit_workflow.md`, the 2 existing `code_styleguides/*.md`, and the 4 `.agents/policies/*.toml` + 7 `.agents/tools/*.json`). Then I cross-referenced each against the 7 new session artifacts (nagent_review, 3 docs guides, ASCII-sketch workflow, SSDL digest, C11 interop v1+v2, 2 new tracks) and the 3 user-correction patterns (duffle-as-style-ref, v2 request/response model, "only under hard constraint"). The audit identifies 10 specific gaps, each with WHY (the session evidence) and HOW (the proposed fix). + +--- + +## 0. The summary verdict + +**10 recommendations across 3 priorities:** + +| # | Priority | Recommendation | Effort | +|---|---|---|---| +| 1 | HIGH | Add the 3 new docs guides + 7 session reports to the architecture-fallback list in `workflow.md` + each SKILL.md | small | +| 2 | HIGH | Document the ASCII-sketch UX workflow in `workflow.md` (new methodology, not in current docs) | small | +| 3 | HIGH | Document the SSDL digest in `product-guidelines.md` (the "Phase 5: Heavy Curation" section) + each SKILL.md architecture-fallback | small | +| 4 | HIGH | Add "Per-Track User-Corrections Log" pattern to the State.toml Template in `workflow.md` (it emerged this session) | small | +| 5 | MEDIUM | Document the "contingency track" pattern in `workflow.md` (chunkification is the first instance) | small | +| 6 | MEDIUM | Update the Compaction Recovery section in `AGENTS.md` to reference the new `session_synthesis_*.md` pattern (not just PLANNING_DIGEST) | small | +| 7 | MEDIUM | Add the "v1→v2 framing iteration" anti-pattern to `workflow.md` (the user pushed back 3 times this session; the workflow should formalize how to handle it) | small | +| 8 | MEDIUM | Document the "preserve-before-compact archive" pattern in `workflow.md` (the user explicitly asked for it at 94% context) | small | +| 9 | LOW | Document the "MiniMax understand_image for ASCII-vs-screenshot verification" workflow in `workflow.md` (the new track uses it) | small | +| 10 | LOW | Document the "per-proposal commit chain with git notes" pattern in `workflow.md` (5+ commits this session) | small | + +**Total: 10 small-doc-updates, no code changes.** If the user approves all 10, the changes are 2-3 hours of focused editing. If they approve just the 4 HIGH-priority ones, ~1 hour. + +--- + +## 1. The 10 recommendations in detail + +### 1.1 (HIGH) Update the architecture-fallback list with the new docs + +**Why.** This session produced 3 new deep-dive guides (commits `ba051684`): +- `docs/guide_discussions.md` (353 lines, 23-op matrix A1-A7 + B1-B11 + C1-C5) +- `docs/guide_state_lifecycle.md` (375 lines, UISnapshot + HistoryManager + 4-thread access pattern) +- `docs/guide_context_aggregation.md` (394 lines, aggregate.py + 7 view modes + 3 strategies + FileItem + ContextPreset) + +**None of these are in the current architecture-fallback list in `conductor/workflow.md` §"Architecture Documentation Fallback" or in any of the SKILL.md files.** The next Tier 1 orchestrator who loads `mma-tier1-orchestrator` SKILL.md will not see these 3 guides as required reading. The next Tier 2 tech lead who loads `mma-tier2-tech-lead` SKILL.md won't see them either. + +**How.** In each of the 5 SKILL.md files (mma-orchestrator, mma-tier1-orchestrator, mma-tier2-tech-lead, mma-tier3-worker, mma-tier4-qa) and in `conductor/workflow.md` §"Architecture Documentation Fallback" + `conductor/index.md` §"Human-Facing Documentation" + `conductor/product-guidelines.md` §"See Also — Applied Conventions": + +Add the 3 new guides to the existing 11-guide index. Cite them with their line counts (so the next agent knows the depth). Add the 7 session reports (`docs/reports/`) to a separate "Session Archives" section so they're discoverable for compaction recovery. + +**Effort:** ~30 min for 6 file edits. 1-line per guide per file. + +### 1.2 (HIGH) Document the ASCII-sketch UX workflow + +**Why.** The ASCII-sketch workflow (formalized in `docs/reports/ascii_sketch_ux_workflow_20260608.md`, 340 lines) is a new methodology the project has. It's NOT in `workflow.md`, `AGENTS.md`, or any SKILL.md. The next agent who tries to design a GUI change will not know this workflow exists. The new `manual_ux_validation_20260608_PLACEHOLDER` track depends on the workflow being discoverable. + +**How.** Add a new section to `conductor/workflow.md` (or a new top-level section in the "Planning Session Workflow" block): + +> ### ASCII-Sketch UX Workflow (NEW 2026-06-08) +> For interactive GUI ideation, the project has a 5-step ASCII-sketch workflow documented in `docs/reports/ascii_sketch_ux_workflow_20260608.md` (340 lines). The workflow uses a fixed 10-convention vocabulary (proposed; the user can override per `conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/decisions.md` once Phase 1 is resolved). When designing a new panel or a substantial redesign of an existing one, run the workflow with the user before writing code. The locked design becomes the contract for the implementing Tier-3 worker. Verification uses `MiniMax understand_image` to compare the rendered GUI screenshot to the locked ASCII. + +**Effort:** ~15 min. 1 new section in workflow.md (~30 lines). + +### 1.3 (HIGH) Document the SSDL digest + +**Why.** The SSDL digest (formalized in `docs/reports/computational_shapes_ssdl_digest_20260608.md`, 504 lines, 30KB) is a new vocabulary + theoretical foundation the project has. The product-guidelines.md §"Code Standards & Architecture" already mentions "Fleury, Acton, Muratori, Blow" as the design influences, but doesn't link to the SSDL digest. The architecture-fallback in each SKILL.md doesn't include it. The Tier 1 orchestrator's "Surgical Spec Protocol" doesn't reference it. The next agent who wants to use the SSDL vocabulary for code-shape sketching won't know the digest exists. + +**How.** Add to `conductor/product-guidelines.md` §"Phase 5: Heavy Curation & Structural Integrity (MANDATORY)" — the existing section already lists the 4 engineers by name; add a 5th bullet pointing at the SSDL digest: + +> **SSDL Vocabulary (NEW 2026-06-08):** For sketching the *computational shape* of code (codepaths, codecycles, branches, merges, nil sentinels, generational handles), use the SSDL vocabulary documented in `docs/reports/computational_shapes_ssdl_digest_20260608.md` (504 lines; 6 primitives + 7 modifiers + 5 defusing techniques + "domain vs systems" lens + "assume as much as possible" lens). **SSDL ≠ GUI ASCII** — SSDL is for code shapes; the ASCII-sketch workflow (`docs/reports/ascii_sketch_ux_workflow_20260608.md`) is for ImGui panel sketches. Use both in the same spec/plan when appropriate. + +Also add the SSDL digest to the architecture-fallback list in each SKILL.md (same pattern as 1.1). + +**Effort:** ~20 min. 1 new bullet in product-guidelines.md + 6 file edits to the SKILL.md files. + +### 1.4 (HIGH) Add the Per-Track User-Corrections Log pattern to State.toml Template + +**Why.** This session's `nagent_review_20260608/state.toml` introduced a `[user_corrections_log]` section with 7 entries documenting 3 rounds of corrections. The pattern is: + +```toml +[user_corrections_log] +# Corrections applied to the first draft based on direct user feedback during review +# Format: 2026-06-08_NN = "correction" (NN is sequence number to ensure TOML key uniqueness) +2026-06-08_1 = "Editable discussions: PARTIAL -> PARITY (DIFFERENT FOCUS). User pointed at HistoryManager..." +2026-06-08_2 = "Per-file memory: DOMAIN MISMATCH -> MANUAL SLOP IS STRONGER IN CURATION DIMENSION..." +``` + +This is **NOT** in the current `workflow.md` §"State.toml Template". The next Tier 1 orchestrator who creates a reference/analysis track (like nagent_review) will not know to add this section, and the user-corrections will be lost in the report.md (where they are easy to miss when re-anchoring after compaction). + +**How.** Add to `conductor/workflow.md` §"State.toml Template", a new `[user_corrections_log]` template entry: + +```toml +[user_corrections_log] +# Optional. For reference/analysis tracks (or any track where the user reviews +# drafts and provides corrections), record the user-corrections in TOML. +# Format: _ = "". NN is a sequence number (1, 2, 3...) +# to ensure TOML key uniqueness when multiple corrections happen on the same day. +# Each entry should be a self-contained one-sentence summary of the correction. +# The full context (what the user said, what the agent changed in response) lives +# in the report.md or comparison_table.md; this log is the index. +2026-06-08_1 = "Editable discussions: PARTIAL -> PARITY (DIFFERENT FOCUS). User pointed at HistoryManager..." +``` + +**Effort:** ~10 min. 1 new template entry in workflow.md. + +### 1.5 (MEDIUM) Document the contingency track pattern + +**Why.** The `chunkification_optimization_20260608_PLACEHOLDER` track introduced a new pattern: a **contingency track** with only 4 artifacts (spec.md, metadata.json, state.toml, index.md) and NO plan.md. The contingency track is documented as "DEFERRED" with explicit activation criteria in metadata.json. It does NOT appear in the active queue of `conductor/tracks.md`; it appears in the Backlog/Contingency section as a *reference*, not a *commitment*. + +This is a useful pattern for any future "wait for the right moment" work — e.g., a "perf optimization if profiling shows X" track, a "specific vendor integration if user picks this provider" track. The current `workflow.md` only describes "full" tracks (spec + plan + implementation). + +**How.** Add a new section to `conductor/workflow.md` §"Planning Session Workflow": + +> ### Contingency Tracks (Optional Pattern) +> For tracks where the *when* is uncertain ("only worth it if X happens"), use the contingency-track pattern. Differences from a full track: +> - **No plan.md.** The plan is not yet known because the activation criteria may change the plan. +> - **Status: deferred** in `metadata.json` and `state.toml` (NOT `active`). +> - **Activation criteria** are explicit in `metadata.json` and §1 of `spec.md`. +> - The `spec.md` is a 1-2 page contingency document, not a full design. +> - Appears in `conductor/tracks.md` Backlog/Contingency section, not Active. +> +> **When to use:** any track where the user says "wait until X is true" or "only do this if Y happens." The pattern keeps the activation scope defined so when the day comes, the work is scoped. +> +> **First instance:** `conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/` (4 artifacts, 1-page spec, activates on hard-constraint profiling evidence). + +**Effort:** ~15 min. 1 new section in workflow.md. + +### 1.6 (MEDIUM) Update Compaction Recovery to reference session_synthesis + +**Why.** The current `AGENTS.md` §"Compaction Recovery" says: + +> 1. **Read the most recent `docs/reports/PLANNING_DIGEST_.md`** if one exists. It indexes the planning artifacts and explains the design decisions behind the active tracks. + +But this session's pattern is the **`session_synthesis_.md`** (579 lines, 40KB) — a richer format that supersedes the PLANNING_DIGEST. The session_synthesis includes: +- Every artifact produced that session +- The 5 source transcripts as minimum-sufficient context +- The 10-commit chain +- The "what the user should know" handoff for the next session +- Cross-references for re-anchoring + +The next agent who compacts will follow the AGENTS.md instruction and look for PLANNING_DIGEST, not session_synthesis, and will miss the new pattern. + +**How.** Update `AGENTS.md` §"Compaction Recovery" step 1: + +> 1. **Read the most recent `docs/reports/session_synthesis_.md`** if one exists. (Newer pattern as of 2026-06-08; supersedes the older `PLANNING_DIGEST_.md` format.) It indexes the session's artifacts, lists the 5 source transcripts as the minimum-sufficient context, and explains the design decisions behind any active tracks. If a session_synthesis exists, prefer it; if only a PLANNING_DIGEST exists, use that as the fallback. + +**Effort:** ~5 min. 1 line edit in AGENTS.md. + +### 1.7 (MEDIUM) Document the v1→v2 framing iteration anti-pattern + +**Why.** This session, the user pushed back 3 times on the same proposal (the v1 C11 interop assessment for the chunkification track): + +- v1: "build a stateful C extension with Python-facing API" (assumed need) +- user correction 1: "duffle.h is a style reference, not an interop pattern" (reframed scope) +- v2: "build a request/response blob pipeline, only under hard constraint" (changed when + what) +- (no user correction 3 needed; v2 was accepted) + +The workflow.md does not document this **"framing iteration" pattern** as an anti-pattern. The next agent who proposes a track will: +- Propose v1 with their best guess +- Get user-correction 1 → revise to v2 +- Get user-correction 2 → revise to v3 +- Each iteration is a partial commit, but the v1 framing may linger in the spec/plan + +**How.** Add a new "Known Pitfalls" entry to `conductor/workflow.md` (next to the existing Defer-Not-Catch, Indentation-Driven Class Method, etc.): + +> ### Framing Iteration (the v1→v2→v3 Proposal Pattern) +> When proposing a track or assessment, the first draft is often wrong about **scope, shape, OR when**. The user is the product owner and will push back if the first draft over-engineers. The correct response is to **supersede** the v1 (clearly mark v1 as superseded), commit the v2 as a separate revision, and document the iteration in the user_corrections_log. +> +> **Anti-patterns to avoid:** +> - **Soft-revising v1 in place.** The v1 framing lingers in the doc even after v2 is written; the next agent reads both and is confused. +> - **Burying the v1 in a v2 commit message.** Future readers can't find the v1 framing to understand what was *not* chosen. +> - **Bailing on the proposal entirely.** The v1 was a reasonable first guess; the v2 is better; the v2 is still a real track/proposal. +> +> **Correct pattern (from this session's C11 interop assessment):** +> 1. Commit v1 as the first draft (commit `68354841`). +> 2. When the user pushes back, mark v1's recommendation as "SUPERSEDED — see Part 3" (per the assessment doc's §4). +> 3. Add Part 3 to the SAME document, as a clearly-labeled revision. Don't start a new file. +> 4. Commit v2 as a separate commit (commit `12311190`). +> 5. Record the user-correction in the v1 → v2 transition log. +> 6. The v2 is the action-oriented section; the v1 stays as background. +> +> **Reference:** `docs/reports/c11_python_interop_assessment_20260608.md` — the v1 (stateful C extension model) and v2 (request/response blob pipeline model) are both preserved in the same doc, with v1 explicitly marked superseded. + +**Effort:** ~20 min. 1 new pitfall entry in workflow.md (~40 lines). + +### 1.8 (MEDIUM) Document the preserve-before-compact archive pattern + +**Why.** At 94% context (478,992 tokens), the user explicitly asked for "the biggest in-depth report you can muster... I really liked this session and want to preserve as much information synthesized by it with the last operation batches you can muster." I produced `docs/reports/session_synthesis_20260608.md` (579 lines, 40KB) as the preserve-before-compact archive. + +This pattern is **NEW** — the existing AGENTS.md §"Compaction Recovery" is *post*-compaction (how to re-anchor a new agent). The preserve-before-compact archive is *pre*-compaction (how to set up the next session for success). + +**How.** Add a new section to `AGENTS.md` (or `conductor/workflow.md`) just before §"Compaction Recovery": + +> ### Preserve-Before-Compact Archive (NEW 2026-06-08) +> When context usage exceeds ~80% (or whenever the user signals "preserve" or "save for next session"), produce a comprehensive session-synthesis document. The document is the **minimum-sufficient context** for the next session to re-anchor. +> +> **What to include (12 sections):** +> 1. The session in one paragraph +> 2. Per-artifact: what was built, why, and how (with file:line citations) +> 3. The 5 source transcripts / key reference material +> 4. The 10-commit chain (chronological, with the user's role and your role) +> 5. Per-user-correction: what they said, what changed in response +> 6. Per-track-decision: what was proposed, what was accepted, what was deferred +> 7. The deeper insight (the 1-2 sentence takeaway that survives compaction) +> 8. What the user should know (handoff to next session) +> 9. The session's arc, in one image (optional ASCII flow) +> 10. Appendix: commit chain with git hashes +> 11. Cross-references for re-anchoring +> 12. End-of-session assessment (what new tracks / docs to create) +> +> **Naming convention:** `docs/reports/session_synthesis_.md`. The next session's Compaction Recovery looks for the most recent file matching this pattern. +> +> **First instance:** `docs/reports/session_synthesis_20260608.md` (579 lines, 40KB) — produced at 94% context per the user's explicit "preserve as much as possible" request. + +**Effort:** ~15 min. 1 new section in AGENTS.md (~40 lines). + +### 1.9 (LOW) Document the MiniMax understand_image workflow for ASCII verification + +**Why.** The new `manual_ux_validation_20260608_PLACEHOLDER` track uses `MiniMax understand_image` to compare the locked ASCII sketch to the rendered GUI screenshot. The current `workflow.md` mentions `MiniMax understand_image` only in passing (per the docs/guides index and the 5 `MiniMax understand_image` calls in the agent markdown). The next agent who wants to verify a GUI change against a design contract doesn't have a documented workflow. + +**How.** Add a short section to `conductor/workflow.md` (or include it in §1.2's ASCII-sketch workflow section): + +> ### MiniMax understand_image for Design Verification +> When a design contract is locked (via the ASCII-sketch workflow or otherwise), use `MiniMax understand_image` to compare the rendered GUI screenshot to the design. The tool's `prompt` parameter should describe the design contract in prose; the tool returns a description of the actual rendered GUI; the conductor diffs the two and flags deltas. +> +> **When to use:** +> - Every panel design verification (if Q2 from the ASCII-sketch workflow = "always") +> - NERV theme work (color matters; ASCII can't show it) +> - Custom shader work (NERV FBO shader, etc.) +> - Complex multi-viewport layouts (where placement in space matters) +> - Visual bugs the user can see but can only describe as "this looks wrong" +> +> **When NOT to use:** plain ImGui designs (ASCII is sufficient); routine UI changes (overhead > value). + +**Effort:** ~10 min. 1 new section in workflow.md (~25 lines). + +### 1.10 (LOW) Document the per-proposal commit chain with git notes + +**Why.** This session produced 7+ separate commits, each a discrete proposal/track: + +1. `9cc51ca9` nagent_review track +2. `ba051684` docs refresh +3. `161ebb0d` link fix +4. `77ae2ec7` qwen_llama_grok spec update +5. `0471440c` data_oriented_error_handling spec update +6. `1fb0d79c` data_structure_strengthening spec update +7. `8a597d18` mcp_architecture_refactor spec update +8. `a9333bbb` code_path_audit spec/plan update +9. `77d7dff5` session_synthesis + proposed new tracks +10. `68354841` C11 interop assessment v1 +11. `12311190` C11 interop assessment v2 +12. `816e9f2f` chunkification contingency track +13. `5b3c11a0` manual_ux_validation track +14. `999fdea4` tracks.md + C11 SSDL cross-ref + +The current `workflow.md` §"Commit Guidelines" + §"Attach Task Summary with Git Notes" describe per-task commits within a single track, but don't describe **per-proposal commit chains with git notes summarizing the chain** (the meta-level pattern that emerged this session). + +**How.** Add a short section to `conductor/workflow.md` §"Commit Guidelines" (or a new top-level section): + +> ### Per-Proposal Commit Chains (Session-Level Pattern) +> When a session produces multiple discrete proposals/tracks/reports (not just per-task commits within one track), commit each one separately. Each commit message should: +> - Use a `conductor(...)` or `docs(...)` prefix (matching the existing convention) +> - Reference the source material (which user-correction / which request) +> - List the files in the proposal + their line counts +> - Cross-reference the other proposals in the same session (so a future agent can find the related work) +> +> The git note attached to the commit should summarize the proposal at a level that's useful for the next session (NOT just the per-task detail). The session_synthesis document (see §"Preserve-Before-Compact Archive") ties the chain together. + +**Effort:** ~10 min. 1 new section in workflow.md (~25 lines). + +--- + +## 2. Cross-cutting observations (not direct recommendations) + +### 2.1 The "session archive" pattern is becoming a new artifact class + +This session produced **6+ session-archive documents** in `docs/reports/`: +1. `session_synthesis_20260608.md` (579 lines, 40KB) — the session overview +2. `proposed_new_tracks_20260608.md` (190 lines, 12KB) — the 2 new track proposals +3. `ascii_sketch_ux_workflow_20260608.md` (340 lines, 19KB) — the workflow +4. `computational_shapes_ssdl_digest_20260608.md` (504 lines, 30KB) — the digest +5. `c11_python_interop_assessment_20260608.md` (843 lines, 58KB, 2 versions) — the assessment +6. `nagent_review_20260608/` (full track directory: 7 files, 1784 lines) — the track itself + +This is a **new artifact class** — a session-level synthesis + deep-dive documents that supplement the per-track spec/plan/metadata/state files. The docs/Readme.md doesn't have a section for "session archives" yet. A small follow-up could add a "Session Archives" section to docs/Readme.md with the naming convention (`_.md`) and a description of what each type of doc is for. + +**Not a recommendation** — just an observation. The docs/Readme.md is comprehensive enough that a new agent will find the reports by listing the directory. + +### 2.2 The `scripts/audit_*.py` + `code_styleguides/*.md` pair is well-established but not extended this session + +The existing 6 audit scripts (`audit_gui2_imports.py`, `audit_license_cve.py`, `audit_line_count.py`, `audit_main_thread_imports.py`, `audit_no_models_config_io.py`, `audit_weak_types.py`, `check_imgui_scopes.py`, `check_test_toml_paths.py`) are well-trodden. The 2 existing code styleguides (`config_state_owner.md`, `python.md`) are well-trodden. + +This session did NOT add a new audit script (no new convention needs enforcement at the script level). It DID add 2 new document types (the ASCII-sketch workflow, the SSDL digest) that *could* have an audit script + styleguide pair, but the nature of these documents (methodology + vocabulary) doesn't lend itself to static analysis. The verification is by *use*, not by *static check*. So the absence of an audit is correct. + +**Not a recommendation** — the existing pattern is being honored. + +### 2.3 The "track" is becoming a more flexible artifact + +The track directory pattern (spec + plan + metadata + state + index) was established for "full" tracks that get implemented. This session introduced 2 variations: + +1. **Contingency track** (chunkification): 4 artifacts, no plan, deferred status, activation criteria +2. **Reference/analysis track** (nagent_review): 7 artifacts, no plan, "active (reference artifacts ready; awaiting human review)" status + +The current workflow.md describes the full track pattern but not these variations. **Recommendations 1.5 (contingency)** addresses the first variation. The reference/analysis track variation is partially addressed by the existing `nagent_review` track's metadata.json pattern but isn't documented as a separate pattern in workflow.md. + +A future recommendation (out of scope for this audit): document the reference/analysis track pattern as a third variation. + +### 2.4 The `track_id` naming convention has a `_PLACEHOLDER` suffix + +The 2 new tracks created this session use the suffix `manual_ux_validation_20260608_PLACEHOLDER` and `chunkification_optimization_20260608_PLACEHOLDER`. The `_PLACEHOLDER` suffix indicates "the track_id may change when the proposal is approved" (per the user's pre-approval convention). + +This convention is implicit (not documented). The next agent who creates a "proposal" track should know to use the `_PLACEHOLDER` suffix. A small addition to the workflow.md §"Planning Session Workflow" could document this. + +**Not a recommendation** — minor; not enough evidence yet to formalize. + +--- + +## 3. The recommended action order + +If the user wants to act on the HIGH-priority recommendations (1.1, 1.2, 1.3, 1.4) in this session, the order is: + +1. **1.1** (HIGH) Update the architecture-fallback lists — 30 min, 6 file edits +2. **1.2** (HIGH) Add the ASCII-sketch workflow to workflow.md — 15 min, 1 section +3. **1.3** (HIGH) Add the SSDL digest to product-guidelines.md + 5 SKILL.md files — 20 min, 6 file edits +4. **1.4** (HIGH) Add the user_corrections_log to State.toml Template — 10 min, 1 template entry + +Total: ~75 min of focused editing. No code changes. All committed in 1-3 commits (1 per file family, or 1 mega-commit if the user prefers). + +If the user wants to act on the MEDIUM-priority too, add 1.5, 1.6, 1.7, 1.8: another ~55 min, 4 sections. + +If the user wants all 10: ~2-3 hours total. + +--- + +## 4. What this audit does NOT recommend + +To be explicit about what the audit is *not* proposing: + +- **Not** changing the TDD protocol. It works. Don't touch it. +- **Not** changing the per-task commit discipline. It works. +- **Not** changing the 4-tier MMA model. The Tier 1/2/3/4 split is well-established and used correctly this session. +- **Not** adding new tier-roles or new agent files. The 4 existing tiers cover the work. +- **Not** changing `conductor/product.md` (the product vision). It's stable. +- **Not** changing `conductor/tech-stack.md`. The stack is stable. +- **Not** changing the existing `python.md` styleguide. The session didn't surface a conflict. +- **Not** changing the existing `config_state_owner.md` styleguide. The session didn't surface a conflict. +- **Not** adding new audit scripts. No new convention needs static enforcement. +- **Not** updating `docs/Readme.md` to add the 2 new reports. The `docs/reports/` directory listing is already comprehensive. + +--- + +## 5. The meta-pattern + +Across the 10 recommendations, there's a single underlying theme: **the workflow/agent markdown is the *theoretical* contract for the project; the session artifacts are the *empirical* evidence; when the two diverge, update the theory to match the evidence**. + +This session's evidence: +- A new methodology emerged (ASCII-sketch workflow) — workflow.md should know about it +- A new vocabulary emerged (SSDL) — product-guidelines.md should know about it +- A new pattern emerged (preserve-before-compact archive) — AGENTS.md should know about it +- A new convention emerged (contingency track, per-proposal commit chain, user-corrections log) — workflow.md should know about it +- A new anti-pattern emerged (framing iteration v1→v2→v3) — workflow.md should know about it + +The 10 recommendations are the *operationalization* of "update the theory to match the evidence." If the user agrees, the next session re-anchors faster, the next agent makes fewer wrong assumptions, and the next user-correction round goes faster. + +**The alternative** — leave the workflow/agent markdown as-is — means the next session's Tier 1 orchestrator re-derives these patterns from scratch, takes longer, and may make different choices. + +--- + +*End of audit. 10 recommendations; 4 HIGH priority; ~75 min to act on the HIGHs. User picks which to commit.*