From 0b2bda5271ff8e819c85e5060ef1fda3299b85f4 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 5 Jul 2026 13:31:22 -0400 Subject: [PATCH] =?UTF-8?q?conductor(track):=20superpowers=20review=20sect?= =?UTF-8?q?ion=2014=20=E2=80=94=20writing-skills=20(medium)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- JOURNAL.md | 108 -------------- TODO.md | 133 ------------------ .../superpowers_review_20260619/report.md | 76 +++++++++- 3 files changed, 75 insertions(+), 242 deletions(-) delete mode 100644 JOURNAL.md delete mode 100644 TODO.md diff --git a/JOURNAL.md b/JOURNAL.md deleted file mode 100644 index 9c48c58e..00000000 --- a/JOURNAL.md +++ /dev/null @@ -1,108 +0,0 @@ -# Engineering Journal - -## 2026-02-28 14:43 - -### Documentation Framework Implementation -- **What**: Implemented Claude Conductor modular documentation system -- **Why**: Improve AI navigation and code maintainability -- **How**: Used `npx claude-conductor` to initialize framework -- **Issues**: None - clean implementation -- **Result**: Documentation framework successfully initialized - ---- - ---- - -## 2026-03-02 - -### Track: context_token_viz_20260301 — Completed |TASK:context_token_viz_20260301| -- **What**: Token budget visualization panel (all 3 phases) -- **Why**: Zero visibility into context window usage; `get_history_bleed_stats` existed but had no UI -- **How**: Extended `get_history_bleed_stats` with `_add_bleed_derived` helper (adds 8 derived fields); added `_render_token_budget_panel` with color-coded progress bar, breakdown table, trim warning, Gemini/Anthropic cache status; 3 auto-refresh triggers (`_token_stats_dirty` flag); `/api/gui/token_stats` endpoint; `--timeout` flag on `claude_mma_exec.py` -- **Issues**: `set_file_slice` dropped `def _render_message_panel` line — caught by outline check, fixed with 1-line insert. Tier 3 delegation via `run_powershell` hard-capped at 60s — implemented changes directly per user approval; added `--timeout` flag for future use. -- **Result**: 17 passing tests, all phases verified by user. Token panel visible in AI Settings under "Token Budget". Commits: 5bfb20f → d577457. - -### Next: mma_agent_focus_ux (planned, not yet tracked) -- **What**: Per-agent filtering for MMA observability panels (comms, tool calls, discussion, token budget) -- **Why**: All panels are global/session-scoped; in MMA mode with 4 tiers, data from all agents mixes. No way to isolate what a specific tier is doing. -- **Gap**: `_comms_log` and `_tool_log` have no tier/agent tag. `mma_streams` stream_id is the only per-agent key that exists. -- **See**: conductor/tracks.md for full audit and implementation intent. - ---- - -## 2026-03-02 (Session 2) - -### Tracks Initialized: feature_bleed_cleanup + mma_agent_focus_ux |TASK:feature_bleed_cleanup_20260302| |TASK:mma_agent_focus_ux_20260302| -- **What**: Audited codebase for feature bleed; initialized 2 new conductor tracks -- **Why**: Entropy from Tier 2 track implementations — redundant code, dead methods, layout regressions, no tier context in observability -- **Bleed findings** (gui_2.py): Dead duplicate `_render_comms_history_panel` (3041-3073, stale `type` key, wrong method ref); dead `begin_main_menu_bar()` block (1680-1705, Quit has never worked); 4 duplicate `__init__` assignments; double "Token Budget" label with no collapsing header -- **Agent focus findings** (ai_client.py + conductors): No `current_tier` var; Tier 3 swaps callback but never stamps tier; Tier 2 doesn't swap at all; `_tool_log` is untagged tuple list -- **Result**: 2 tracks committed (4f11d1e, c1a86e2). Bleed cleanup is active; agent focus depends on it. - -- **More Tracks**: Initialized 'tech_debt_and_test_cleanup_20260302' and 'conductor_workflow_improvements_20260302' to harden TDD discipline, resolve test tech debt (false-positives, dupes), and mandate AST-based codebase auditing. -- **Final Track**: Initialized 'architecture_boundary_hardening_20260302' to fix the GUI HITL bypass allowing direct AST mutations, patch token bloat in `mma_exec.py`, and implement cascading blockers in `dag_engine.py`. -- **Testing Consolidation**: Initialized 'testing_consolidation_20260302' track to standardize simulation testing workflows around the pytest `live_gui` fixture and eliminate redundant `subprocess.Popen` wrappers. -- **Dependency Order**: Added an explicit 'Track Dependency Order' execution guide to `conductor/tracks.md` to ensure safe progression through the accumulated tech debt. -- **Documentation**: Added guide_meta_boundary.md to explicitly clarify the difference between the Application's strict-HITL environment and the autonomous Meta-Tooling environment, helping future Tiers avoid feature bleed. -- **Heuristics & Backlog**: Added Data-Oriented Design and Immediate Mode architectural heuristics (inspired by Muratori/Acton) to product-guidelines.md. Logged future decoupling and robust parsing tracks to a 'Future Backlog' in TASKS.md. - ---- - -## 2026-03-02 (Session 3) - -### Track: feature_bleed_cleanup_20260302 — Completed |TASK:feature_bleed_cleanup_20260302| -- **What**: Removed all confirmed dead code and layout regressions from gui_2.py (3 phases) -- **Why**: Tier 3 workers had left behind dead duplicate methods, dead menu block, duplicate state vars, and a broken Token Budget layout that embedded the panel inside Provider & Model with double labels -- **How**: - - Phase 1: Deleted dead `_render_comms_history_panel` duplicate (stale `type` key, nonexistent `_cb_load_prior_log`, `scroll_area` ID collision). Deleted 4 duplicate `__init__` assignments (ui_new_track_name etc.) - - Phase 2: Deleted dead `begin_main_menu_bar()` block (24 lines, always-False in HelloImGui). Added working `Quit` to `_show_menus` via `runner_params.app_shall_exit = True` - - Phase 3: Removed 4 redundant Token Budget labels/call from `_render_provider_panel`. Added `collapsing_header("Token Budget")` to AI Settings with proper `_render_token_budget_panel()` call -- **Issues**: Full test suite hangs (pre-existing — `test_suite_performance_and_flakiness` backlog). Ran targeted GUI/MMA subset (32 passed) as regression proxy. Meta-Level Sanity Check: 52 ruff errors in gui_2.py before and after — zero new violations introduced -- **Result**: All 3 phases verified by user. Checkpoints: be7174c (Phase 1), 15fd786 (Phase 2), 0d081a2 (Phase 3) - ---- - -## 2026-03-02 (Session 4) - -### Track: mma_agent_focus_ux_20260302 — Completed |TASK:mma_agent_focus_ux_20260302| -- **What**: Per-tier agent focus UX — source_tier tagging + Focus Agent filter UI (all 3 phases) -- **Why**: All MMA observability panels were global/session-scoped; traffic from Tier 2/3/4 was indistinguishable -- **How**: - - Phase 1: Added `current_tier: str | None` module var to `ai_client.py`; `_append_comms` stamps `source_tier: current_tier` on every comms entry; `run_worker_lifecycle` sets `"Tier 3"` / `generate_tickets` sets `"Tier 2"` around `send()` calls, clears in `finally`; `_on_tool_log` captures `current_tier` at call time; `_append_tool_log` migrated from tuple to dict with `source_tier` field; `_pending_tool_calls` likewise. Checkpoint: bc1a570 - - Phase 2: `_render_tool_calls_panel` migrated from tuple destructure to dict access. Checkpoint: 865d8dd - - Phase 3: `ui_focus_agent: str | None` state var added; Focus Agent combo (All/Tier2/3/4) + clear button above OperationsTabs; filter logic in `_render_comms_history_panel` and `_render_tool_calls_panel`; `[source_tier]` label per comms entry header. Checkpoint: b30e563 -- **Issues**: - - `claude_mma_exec.py` fails with nested session block — user authorized inline implementation for this track - - Task 2.1 set_file_slice applied at shifted line, leaving stale tuple destructure + missing `i = i_minus_one + 1`; caught and fixed in Phase 3 Task 3.4 - - **Known limitation**: `current_tier` is a module-level `str | None` — safe only because MMA engine serializes `send()` calls. Concurrent Tier 3/4 agents (future) will require `threading.local()` or per-ticket context passing. Logged to backlog. - - **Verification gap noted**: No API hook endpoints expose `ui_focus_agent` state for automated testing. Future tracks should wire widget state to `_settable_fields` for `live_gui` fixture verification. Logged to backlog. -- **Result**: 18 tests passing. Focus Agent combo visible in Operations Hub. Comms entries show `[main]`/`[Tier N]` labels. Meta-Level Sanity Check: 53 ruff errors in gui_2.py before and after — zero new violations. - ---- - -## 2026-03-02 (Session 5) - -### Track: tech_debt_and_test_cleanup_20260302 — Botched / Archived -- **What**: Attempted to centralize test fixtures and enforce test discipline. -- **Issues**: Track was launched with a flawed specification that misidentified critical headless API endpoints as "dead code." While centralized `app_instance` fixtures were successfully deployed, it exposed several zero-assertion tests and exacerbated deep architectural issues with the `asyncio` loop lifecycle, causing widespread `RuntimeError: Event loop is closed` warnings and test hangs. -- **Result**: Track was aborted and archived. A post-mortem `DEBRIEF.md` was generated. - -### Strategic Shift: The Strict Execution Queue -- **What**: Systematically audited the Future Backlog and converted all pending technical debt into a strict, 9-track, linearly ordered execution queue in `conductor/tracks.md`. -- **Why**: "Mock-Rot" and stateless Tier 3 entropy. Tier 3 workers were blindly using `unittest.mock.patch` to pass tests without testing integration realities, creating a false sense of security. -- **How**: - - Defined the "Surgical Spec Protocol" to force Tier 1/2 agents to map exact `WHERE/WHAT/HOW/SAFETY` targets for workers. - - Initialized 7 new tracks: `test_stabilization_20260302`, `strict_static_analysis_and_typing_20260302`, `codebase_migration_20260302`, `gui_decoupling_controller_20260302`, `hook_api_ui_state_verification_20260302`, `robust_json_parsing_tech_lead_20260302`, `concurrent_tier_source_tier_20260302`, and `test_suite_performance_and_flakiness_20260302`. - - Added a highly interactive `manual_ux_validation_20260302` track specifically for tuning GUI animations and structural layout using a slow-mode simulation harness. -- **Result**: The project now has a crystal-clear, heavily guarded roadmap to escape technical debt and transition to a robust, Data-Oriented, type-safe architecture. -## 2026-03-02: Test Suite Stabilization & Simulation Hardening -* **Track:** Test Suite Stabilization & Consolidation -* **Outcome:** Track Completed Successfully -* **Key Accomplishments:** - * **Asyncio Lifecycle Fixes:** Eliminated pervasive Event loop is closed and coroutine was never awaited warnings in tests. Refactored conftest.py teardowns and test loop handling. - * **Legacy Cleanup:** Completely removed gui_legacy.py and updated all 16 referencing test files to target gui_2.py, consolidating the architecture. - * **Functional Assertions:** Replaced pytest.fail placeholders with actual functional assertions in pi_events, execution_engine, oken_usage, gent_capabilities, and gent_tools_wiring test suites. - * **Simulation Hardening:** Addressed flakiness in est_extended_sims.py. Fixed timeouts and entry count regressions by forcing explicit GUI states (uto_add_history=True) during setup, and refactoring wait_for_ai_response to intelligently detect turn completions and tool execution stalls based on status transitions rather than just counting messages. - * **Workflow Updates:** Updated conductor/workflow.md to establish a new rule forbidding full suite execution (pytest tests/) during verification to prevent long timeouts and threading access violations. Demanded batch-testing (max 4 files) instead. - * **New Track Proposed:** Created sync_tool_execution_20260303 track to introduce concurrent background tool execution, reducing latency during AI research phases. -* **Challenges:** The extended simulation suite ( est_extended_sims.py) was highly sensitive to the exact transition timings of the mocked gemini_cli and the background threading of gui_2.py. Required multiple iterations of refinement to simulation/workflow_sim.py to achieve stable, deterministic execution. The full test suite run proved unstable due to accumulation of open threads/loops across 360+ tests, necessitating a shift to batch-testing. diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 908a0b0d..00000000 --- a/TODO.md +++ /dev/null @@ -1,133 +0,0 @@ -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 8040: character maps to -[DEBUG] Saving config. Theme: {'palette': '10x Dark', 'font_path': 'fonts/MapleMono-Regular.ttf', 'font_size': 20.0, 'scale': 1.0, 'transparency': 1.0, 'child_transparency': 1.0, 'tone_mapping': {'solarized_light': {'brightness': 0.6899999976158142, 'contrast': 0.8600000143051147, 'gamma': 0.7699999809265137}, 'gray_variations': {'brightness': 0.7699999809265137, 'contrast': 0.7200000286102295, 'gamma': 0.6899999976158142}, 'moss': {'brightness': 0.7699999809265137, 'contrast': 0.8700000047683716, 'gamma': 1.0}, 'Solarized Light': {'brightness': 0.550000011920929, 'contrast': 0.7300000190734863, 'gamma': 0.7099999785423279}, 'Binks': {'brightness': 0.47999998927116394, 'contrast': 0.8399999737739563, 'gamma': 2.2100000381469727}}} -Exception in thread Thread-506 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -Exception in thread Thread-511 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -Exception in thread Thread-516 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -Exception in thread Thread-521 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -Exception in thread Thread-526 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -[DEBUG] Saving config. Theme: {'palette': '10x Dark', 'font_path': 'fonts/MapleMono-Regular.ttf', 'font_size': 20.0, 'scale': 1.0, 'transparency': 1.0, 'child_transparency': 1.0, 'tone_mapping': {'solarized_light': {'brightness': 0.6899999976158142, 'contrast': 0.8600000143051147, 'gamma': 0.7699999809265137}, 'gray_variations': {'brightness': 0.7699999809265137, 'contrast': 0.7200000286102295, 'gamma': 0.6899999976158142}, 'moss': {'brightness': 0.7699999809265137, 'contrast': 0.8700000047683716, 'gamma': 1.0}, 'Solarized Light': {'brightness': 0.550000011920929, 'contrast': 0.7300000190734863, 'gamma': 0.7099999785423279}, 'Binks': {'brightness': 0.47999998927116394, 'contrast': 0.8399999737739563, 'gamma': 2.2100000381469727}}} -[DEBUG] Saving config. Theme: {'palette': '10x Dark', 'font_path': 'fonts/MapleMono-Regular.ttf', 'font_size': 20.0, 'scale': 1.0, 'transparency': 1.0, 'child_transparency': 1.0, 'tone_mapping': {'solarized_light': {'brightness': 0.6899999976158142, 'contrast': 0.8600000143051147, 'gamma': 0.7699999809265137}, 'gray_variations': {'brightness': 0.7699999809265137, 'contrast': 0.7200000286102295, 'gamma': 0.6899999976158142}, 'moss': {'brightness': 0.7699999809265137, 'contrast': 0.8700000047683716, 'gamma': 1.0}, 'Solarized Light': {'brightness': 0.550000011920929, 'contrast': 0.7300000190734863, 'gamma': 0.7099999785423279}, 'Binks': {'brightness': 0.47999998927116394, 'contrast': 0.8399999737739563, 'gamma': 2.2100000381469727}}} -Exception in thread Thread-540 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 527: character maps to -Exception in thread Thread-545 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -Exception in thread Thread-550 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 7874: character maps to -Exception in thread Thread-555 (_readerthread): -Traceback (most recent call last): - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 1045, in _bootstrap_inner - self.run() - File "C:\Users\Ed\scoop\apps\python\current\Lib\threading.py", line 982, in run - self._target(*self._args, **self._kwargs) - File "C:\Users\Ed\scoop\apps\python\current\Lib\subprocess.py", line 1597, in _readerthread - buffer.append(fh.read()) - ^^^^^^^^^ - File "C:\Users\Ed\scoop\apps\python\current\Lib\encodings\cp1252.py", line 23, in decode - return codecs.charmap_decode(input,self.errors,decoding_table)[0] - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -UnicodeDecodeError: 'charmap' codec can't decode byte 0x90 in position 8040: character maps to -[DEBUG] Saving config. Theme: {'palette': '10x Dark', 'font_path': 'fonts/MapleMono-Regular.ttf', 'font_size': 20.0, 'scale': 1.0, 'transparency': 1.0, 'child_transparency': 1.0, 'tone_mapping': {'solarized_light': {'brightness': 0.6899999976158142, 'contrast': 0.8600000143051147, 'gamma': 0.7699999809265137}, 'gray_variations': {'brightness': 0.7699999809265137, 'contrast': 0.7200000286102295, 'gamma': 0.6899999976158142}, 'moss': {'brightness': 0.7699999809265137, 'contrast': 0.8700000047683716, 'gamma': 1.0}, 'Solarized Light': {'brightness': 0.550000011920929, 'contrast': 0.7300000190734863, 'gamma': 0.7099999785423279}, 'Binks': {'brightness': 0.47999998927116394, 'contrast': 0.8399999737739563, 'gamma': 2.2100000381469727}}} diff --git a/conductor/tracks/superpowers_review_20260619/report.md b/conductor/tracks/superpowers_review_20260619/report.md index a83ab3d3..6d95f832 100644 --- a/conductor/tracks/superpowers_review_20260619/report.md +++ b/conductor/tracks/superpowers_review_20260619/report.md @@ -857,7 +857,81 @@ The project's master-direct workflow is an intentional ARCH-DIFF. The skill appl ## 14. Writing Skills - +## 14. Writing Skills + +### 14.1 What the skill prescribes + +The `writing-skills` skill is the meta-skill for creating skills. Core principle: "Writing skills IS Test-Driven Development applied to process documentation." REQUIRED BACKGROUND: superpowers:test-driven-development (the Iron Law applies). Personal skills live in agent-specific directories (`~/.claude/skills/` for Claude Code, `~/.agents/skills/` for Codex). + +The TDD Mapping for Skills: Test case = pressure scenario with subagent; Production code = skill document (SKILL.md); Test fails (RED) = agent violates rule without skill (baseline); Test passes (GREEN) = agent complies with skill present; Refactor = close loopholes while maintaining compliance. + +When to Create a Skill: Technique wasn't intuitively obvious; you'd reference this again across projects; pattern applies broadly (not project-specific); others would benefit. Don't create for: One-off solutions; standard practices well-documented elsewhere; project-specific conventions (put in CLAUDE.md); mechanical constraints (if enforceable with regex/validation, automate it). + +Skill Types: Technique (concrete method with steps); Pattern (way of thinking); Reference (API docs, syntax guides). + +SKILL.md Structure: YAML frontmatter (name, description); Overview (what is this, core principle 1-2 sentences); When to Use (small inline flowchart if decision non-obvious); Core Pattern (before/after comparison); Quick Reference (table for scanning); Implementation (inline code or link to separate file); Common Mistakes; Real-World Impact (optional). + +Claude Search Optimization (CSO): Rich description field (description = when to use, NOT what the skill does; "Use when..." phrasing; third person; never summarize workflow); keyword coverage (error messages, symptoms, tools); descriptive naming (active voice, verb-first, gerunds); token efficiency (getting-started workflows <150 words; frequently-loaded skills <200 words; other skills <500 words). + +Iron Law (same as TDD): NO SKILL WITHOUT A FAILING TEST FIRST. Applies to NEW skills AND EDITS to existing skills. "Write skill before testing? Delete it. Start over." "Edit skill without testing? Same violation." + +Bulletproofing Skills Against Rationalization: Close every loophole explicitly; address "spirit vs letter" arguments; build rationalization table; create red flags list; update CSO for violation symptoms. + +Skill Creation Checklist: RED (write failing test = pressure scenarios, run baseline, identify rationalizations); GREEN (write minimal skill = YAML frontmatter, "Use when" description, third person, keywords, address baseline failures, code inline or link); REFACTOR (close loopholes = identify NEW rationalizations, add explicit counters, build rationalization table, red flags list, re-test); Quality Checks (small flowchart, quick reference, common mistakes, no narrative); Deployment (commit + push). + +### 14.2 Mapping to the project's existing pattern + +The project has 5 MMA skills in `.agents/skills/` (mma-orchestrator, mma-tier1-orchestrator, mma-tier2-tech-lead, mma-tier3-worker, mma-tier4-qa) plus the mirrored `.gemini/skills/` (legacy). These are project-specific skills following a similar structure. + +| Skill rule | Project equivalent | Where | +|---|---|---| +| "Personal skills live in ~/.agents/skills/" | The project's `.agents/skills/` directory has 5 MMA skills; mirrored in `.gemini/skills/` (legacy from Gemini CLI era) | `.agents/skills/`, `.gemini/skills/` | +| "SKILL.md Structure: name, description, Overview, When to Use, Core Pattern, Quick Reference" | The project's MMA skills follow a similar structure (skill name, persona, scope, responsibilities) but with project-specific headings | `.agents/skills/mma-tier3-worker/SKILL.md` (example) | +| "description = when to use, NOT what the skill does" | The project's MMA skill descriptions are persona-flavored ("Stateless Tier 3 Worker for surgical code implementation and TDD") rather than trigger-focused ("Use when X") | `.agents/skills/mma-tier3-worker/SKILL.md` | +| "REQUIRED BACKGROUND: superpowers:test-driven-development" | The project's MMA skills don't reference a TDD-equivalent skill (the TDD discipline is in `conductor/workflow.md` §"Task Workflow") | — | +| "TDD Mapping: pressure scenarios with subagent" | The project's MMA skills don't have pressure-scenario tests; the skills are documented but not tested via the skill's TDD-for-skills methodology | — | +| "Iron Law: NO SKILL WITHOUT A FAILING TEST FIRST" | n/a — the project's MMA skills were authored without explicit pressure-scenario testing | — | +| "Token efficiency: <150 / <200 / <500 words" | The project's MMA skills are 50-300 lines (~500-3000 words); not strictly enforced | — | +| "Cross-referencing Other Skills: skill name only, no @ links" | The project's MMA skills use markdown links to `conductor/workflow.md` and other doc files; no `@`-syntax force-loading | Project-wide | +| "When to Create a Skill: technique wasn't obvious; reusable; broadly applicable" | The 5 MMA skills were created when the 4-tier MMA was designed; they're stable since the `tier2_autonomous_sandbox_20260616` track | `conductor/tracks/tier2_autonomous_sandbox_20260616/` | +| "Don't create for project-specific conventions (put in CLAUDE.md)" | The project's conductor/ workflow + styleguides + AGENTS.md are the project-specific convention home; the MMA skills are the reusable pattern | Project-wide | +| "Directory Structure: skills/skill-name/SKILL.md" | The project uses `.agents/skills/mma-*/SKILL.md` | `.agents/skills/` | +| "Skills are NOT: Narratives about how you solved a problem once" | The project's MMA skills are principles + scope + responsibilities; not narrative | `.agents/skills/mma-*/SKILL.md` | + +### 14.3 Where the project already follows the discipline + +- **The `.agents/skills/` directory structure** is skill-compliant. +- **The 5 MMA skills are stable** (created 2026-06-XX, not modified frequently). +- **The cross-referencing pattern** uses markdown links to `conductor/workflow.md`, not `@`-syntax force-loading. This is skill-compliant. +- **The skill names follow verb-first / active-voice conventions**: mma-tier1-orchestrator (gerund form via noun "orchestrator"), mma-tier3-worker (gerund form), mma-orchestrator (gerund). Slightly different from the skill's "verb-first / active-voice" recommendation but consistent with project convention. + +### 14.4 Where the project doesn't follow the discipline + +- **No pressure-scenario testing.** The MMA skills were authored without explicit baseline-violation tests. The skills may have loopholes that surface under pressure but aren't codified. +- **No token-budget enforcement.** The MMA skills are 50-300 lines (well above the 150/200/500 word targets). They're not "frequently loaded" (the project doesn't auto-load them; they're loaded via Skill tool on demand), but they're longer than the skill recommends. +- **The MMA skill descriptions are persona-flavored** ("Stateless Tier 3 Worker for...") rather than trigger-focused ("Use when X"). Per the skill's CSO rule, "Description = When to Use, NOT What the Skill Does". This is an explicit divergence. +- **The Iron Law "NO SKILL WITHOUT A FAILING TEST FIRST"** is not applied to the project's MMA skills. The deferred rebuild may want to add pressure-scenario testing for each MMA skill. + +### 14.5 Recommendations summary + +The project follows the skill's structure but diverges on three points: descriptions are persona-flavored not trigger-focused; no pressure-scenario testing; longer than recommended. The deferred rebuild may want to: + +- **HIGH:** Add pressure-scenario testing for each MMA skill. The Tier 1 Orchestrator, Tier 2 Tech Lead, Tier 3 Worker, Tier 4 QA, and mma-orchestrator skills should each have a baseline-violation scenario + a skill-with scenario. This is the project's largest gap with the skill. +- **MEDIUM:** Rewrite the MMA skill descriptions to be trigger-focused ("Use when X") rather than persona-flavored. The descriptions are loaded by agents to decide which skill applies; trigger-focused descriptions improve skill-selection accuracy. +- **LOW:** Compress the MMA skills to meet token-budget targets. They're loaded on demand, so the impact is small. + +**Verdict.** + +| Field | Value | +|---|---| +| **Primary** | `PARTIAL` | +| **Integration tag** | `INTEGRATE-PARTIAL` | +| **Section size** | medium | +| **Cross-refs** | nagent_review_20260608 §10 ("durable work" thesis shapes how skills are written); fable_review_20260617 §13 (project's skill-writing pattern is "genuinely useful"); intent_dsl_survey_20260612 §6 (the MMA skill architecture is documented as an "AI-agent property") | + +**Rationale.** The project follows the skill's directory structure and cross-referencing pattern. The 5 MMA skills are stable. Three gaps: persona-flavored descriptions (instead of trigger-focused), no pressure-scenario testing (no Iron Law application), longer than recommended token budgets. The deferred rebuild should add pressure-scenario testing as the highest-priority improvement. + +**Recommended change.** Add pressure-scenario testing for each MMA skill (HIGH); rewrite descriptions to be trigger-focused (MEDIUM); compress to token-budget targets (LOW). ## 15. MMA Skills Cluster