docs(audit): workflow/agent markdown audit with 10 recommendations
User asked: is there anything in our workflow or agent markdown that should be updated or introduced based on this session? This commit is the AUDIT ONLY. No workflow files are modified. The 10 recommendations are not yet applied. User picks which to act on, which to defer, which to discard. docs/reports/workflow_markdown_audit_20260608.md (~370 lines): 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, product.md, product-guidelines.md, tech-stack.md, index.md, tracks.md, edit_workflow.md, the 2 existing code_styleguides/*.md, and the 4 .agents/policies/*.toml + 7 .agents/tools/*.json). 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 10 recommendations: 1 (HIGH) Update architecture-fallback with new docs 2 (HIGH) Document ASCII-sketch workflow in workflow.md 3 (HIGH) Document SSDL digest in product-guidelines.md 4 (HIGH) Add user_corrections_log to State.toml Template 5 (MED) Document contingency track pattern 6 (MED) Update Compaction Recovery to reference session_synthesis 7 (MED) Document v1->v2 framing iteration anti-pattern 8 (MED) Document preserve-before-compact archive pattern 9 (LOW) Document MiniMax understand_image for ASCII verification 10 (LOW) Document per-proposal commit chain with git notes 4 HIGH-priority = ~75 min to act on. All 10 = ~2-3 hours. The audit is conservative: it does NOT recommend changing TDD, the per-task commit discipline, the 4-tier MMA model, product.md, tech-stack.md, the existing styleguides, or adding new audit scripts. The session did not surface conflicts with any of these. Meta-pattern: workflow/agent markdown is the theoretical contract; session artifacts are the empirical evidence; when the two diverge, update the theory to match the evidence. This session's evidence (new methodology, new vocabulary, new patterns, new anti-patterns) drives the 10 recommendations.
This commit is contained in:
conductor-tier2
@@ -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: <YYYY-MM-DD>_<NN> = "<correction>". 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_<date>.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_<date>.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_<date>.md`** if one exists. (Newer pattern as of 2026-06-08; supersedes the older `PLANNING_DIGEST_<date>.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_<YYYY-MM-DD>.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 (`<topic>_<YYYY-MM-DD>.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.*
|
||||
Reference in New Issue
Block a user