Private
Public Access
chore(docs): organize reports into week folders (113 files, 6 weeks)
Moves 113 loose files in docs/reports/ into week folders named <YYYY>-<MM>-<DD> (Monday of the file's week). Weeks created: 2026-03-02, 2026-05-04, 2026-05-11, 2026-06-01, 2026-06-08, 2026-06-15. Current week's files (June 22+) stay in place; 23 in-flight reports remain in docs/reports/ root. Subdirectories code_path_audit/ and license_cve_audit/ untouched.
This commit is contained in:
@@ -1,367 +0,0 @@
|
||||
# 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 + 8-thread io_pool access pattern [was 4-thread pre-2026-06-06 bump in 4a338486])
|
||||
- `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