conductor(track): superpowers review section 14 — writing-skills (medium)
This commit is contained in:
-108
@@ -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.
|
||||
@@ -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 <undefined>
|
||||
[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 <undefined>
|
||||
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 <undefined>
|
||||
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 <undefined>
|
||||
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 <undefined>
|
||||
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 <undefined>
|
||||
[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 <undefined>
|
||||
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 <undefined>
|
||||
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 <undefined>
|
||||
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 <undefined>
|
||||
[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}}}
|
||||
@@ -857,7 +857,81 @@ The project's master-direct workflow is an intentional ARCH-DIFF. The skill appl
|
||||
|
||||
## 14. Writing Skills
|
||||
|
||||
<!-- Section 14 medium (100-250 LOC). Skill: writing-skills. Verdict pending. -->
|
||||
## 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user