340 lines
15 KiB
Markdown
340 lines
15 KiB
Markdown
# Conductor Docs Refresh Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Sync the source-of-truth conductor docs (`conductor/product.md`, `conductor/product-guidelines.md`, `conductor/tech-stack.md`, `conductor/workflow.md`, `conductor/index.md`) to reflect the current state of the codebase after 4 months of evolution since the last docs refresh.
|
|
|
|
**Architecture:** Single-agent sequential execution. Each conductor doc is a self-contained task: audit current claims against the actual codebase, identify drift, rewrite stale sections, commit per-file, attach git note. No new conductor docs are written in this plan (those are out of scope per the spec).
|
|
|
|
**Tech Stack:** Manual Slop's MCP research tools. Git for version control. Markdown for documentation.
|
|
|
|
**Spec:** `docs/superpowers/specs/2026-06-02-comprehensive-documentation-refresh-design.md` §5 (Sub-Track 2).
|
|
|
|
**Depends on:** Sub-Track 1 (`docs_layer_refresh_20260602`) must complete first. The human-facing docs layer is the source of truth that this plan syncs to.
|
|
|
|
---
|
|
|
|
## Execution Constraints
|
|
|
|
These apply to every task in this plan:
|
|
|
|
- **No subagents.** Execute as a single agent. No Tier 3/Tier 4 delegation. No parallel workers.
|
|
- **Pre-edit checkpoint:** Before any file edit, run `git add .` to stage current state.
|
|
- **Per-file atomic commits:** One file = one commit. Never batch.
|
|
- **Commit message format:** `docs(<scope>): <imperative description>`.
|
|
- **Git note format:** Attach a 3-8 line rationale to each commit.
|
|
- **Symbol parity:** Every class, function, module, or dep name in these docs must match the source.
|
|
- **The conductor docs are the source of truth** for the rest of the project. Anything documented here must be verifiable in the codebase.
|
|
|
|
---
|
|
|
|
## Task 1: Sync `conductor/product.md`
|
|
|
|
**Files:**
|
|
- Modify: `conductor/product.md` (current size ~23.1K)
|
|
- Reference: `src/` directory (every module), `docs/Readme.md` (now updated per Sub-Track 1), `docs/guide_*.md`
|
|
|
|
**Scope:** This is the product vision / feature list document. Every feature claim must correspond to a real subsystem. Every subsystem should appear. No "planned" or "in progress" features should be listed as if they exist (unless they're in the active backlog).
|
|
|
|
- [ ] **Step 1.1: Pre-edit checkpoint**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add .
|
|
```
|
|
|
|
- [ ] **Step 1.2: Read the current `conductor/product.md`**
|
|
|
|
Use `manual-slop_get_file_summary` first, then `manual-slop_get_file_slice` for sections.
|
|
|
|
- [ ] **Step 1.3: Inventory every src/ module**
|
|
|
|
Use `manual-slop_list_directory path="C:\projects\manual_slop\src"` to get the current module list. For each module, use `manual-slop_get_file_summary` to understand its purpose.
|
|
|
|
Map each module to a feature. Note: the modules in `src/` are the source of truth for what exists.
|
|
|
|
- [ ] **Step 1.4: Compare modules to feature claims in `product.md`**
|
|
|
|
Build a comparison:
|
|
- **Modules in `src/` not mentioned in `product.md`:** [list] — these are missing features
|
|
- **Features in `product.md` with no corresponding module:** [list] — these are stale claims
|
|
- **Features with a module that does something different than `product.md` claims:** [list] — these are stale descriptions
|
|
|
|
- [ ] **Step 1.5: Add missing features**
|
|
|
|
For each module not mentioned in `product.md`:
|
|
- Find the most relevant existing section in `product.md`
|
|
- Add a sub-bullet or paragraph describing the feature
|
|
- Use the gap analysis from Sub-Track 1's `gap_analysis.md` as a cross-reference
|
|
|
|
Pay particular attention to: RAG, Beads, Hot Reload, Discussion Metrics/Compression, Command Palette, Structural File Editor, NERV Theme, Persona Editor, Workspace Profiles, History (undo/redo), External MCP, Synced HITL Bridge, External Editor Integration.
|
|
|
|
- [ ] **Step 1.6: Remove or correct stale claims**
|
|
|
|
For each feature claim that no longer matches the code:
|
|
- If the feature was removed, delete the claim
|
|
- If the feature was renamed or restructured, update the description
|
|
- If the feature was culled (per the Culling Candidates report), remove the claim
|
|
|
|
- [ ] **Step 1.7: Update the "Primary Use Cases" section**
|
|
|
|
If real-world usage patterns have evolved (e.g., the user mentioned Claude is no longer used), update the use cases to reflect actual current usage.
|
|
|
|
- [ ] **Step 1.8: Validate all cross-doc links**
|
|
|
|
For every `[text](./relative/path)` in the modified `product.md`, verify the target exists.
|
|
|
|
- [ ] **Step 1.9: Commit per-section (one commit per logical group of changes)**
|
|
|
|
For example:
|
|
- If you added 5 new features, that's 1 commit: `docs(product): add RAG, Beads, Hot Reload, and 2 more features`
|
|
- If you corrected 3 stale claims, that's 1 commit: `docs(product): correct stale claims for X, Y, Z`
|
|
- If you removed 2 culled features, that's 1 commit: `docs(product): remove culled features X, Y`
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add conductor/product.md
|
|
git -C C:\projects\manual_slop commit -m "docs(product): <description>"
|
|
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Sync rationale: [what was stale, what was added, what was removed]." $_ }
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: Sync `conductor/tech-stack.md`
|
|
|
|
**Files:**
|
|
- Modify: `conductor/tech-stack.md`
|
|
- Reference: `pyproject.toml`, `requirements.txt`, `src/` (every module)
|
|
|
|
**Scope:** Every entry must be a real Python dep (verify in `pyproject.toml` or `requirements.txt`) or a real `src/` module. No "we use X" claims without verification.
|
|
|
|
- [ ] **Step 2.1: Pre-edit checkpoint**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add .
|
|
```
|
|
|
|
- [ ] **Step 2.2: Read the current `conductor/tech-stack.md`**
|
|
|
|
- [ ] **Step 2.3: Read `pyproject.toml` to get the canonical dep list**
|
|
|
|
Use `manual-slop_read_file` (it's small).
|
|
|
|
- [ ] **Step 2.4: For each dep claim in `tech-stack.md`, verify it exists in `pyproject.toml`**
|
|
|
|
Use `manual-slop_py_find_usages` or grep to confirm. Flag any claim that doesn't match.
|
|
|
|
- [ ] **Step 2.5: For each `src/` module claim in `tech-stack.md`, verify it exists**
|
|
|
|
Use `manual-slop_search_files` to confirm.
|
|
|
|
- [ ] **Step 2.6: Add missing deps and modules**
|
|
|
|
Likely missing entries (verify via Step 2.3-2.5):
|
|
- `chromadb` (RAG)
|
|
- `dolt` or any Beads dep
|
|
- `psutil` (performance monitoring)
|
|
- `pywin32` (window frame manipulation)
|
|
- `pydantic` (if used)
|
|
- New `src/` modules: `rag_engine.py`, `beads_client.py`, `hot_reloader.py`, `history.py`, `workspace_manager.py`, `theme_nerv.py`, `theme_nerv_fx.py`, `personas.py`, `presets.py`, `context_presets.py`, `tool_bias.py`, `tool_presets.py`, `synthesis_formatter.py`, `imgui_scopes.py`, etc.
|
|
|
|
- [ ] **Step 2.7: Remove or correct stale claims**
|
|
|
|
- [ ] **Step 2.8: Validate all cross-doc links**
|
|
|
|
- [ ] **Step 2.9: Commit per-section**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add conductor/tech-stack.md
|
|
git -C C:\projects\manual_slop commit -m "docs(tech-stack): <description>"
|
|
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Sync rationale: [added X deps/modules, removed Y stale claims]." $_ }
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: Sync `conductor/workflow.md`
|
|
|
|
**Files:**
|
|
- Modify: `conductor/workflow.md` (current size ~25.2K)
|
|
- Reference: 5-10 recent completed tracks (read their `plan.md` files), the test suite, the pre-commit/lint scripts
|
|
|
|
**Scope:** The task lifecycle, TDD protocol, phase completion verification, checkpointing. This is the document every conductor-driven agent reads. It must match actual practice.
|
|
|
|
- [ ] **Step 3.1: Pre-edit checkpoint**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add .
|
|
```
|
|
|
|
- [ ] **Step 3.2: Read the current `conductor/workflow.md`**
|
|
|
|
- [ ] **Step 3.3: Spot-check 5 recent completed tracks for workflow compliance**
|
|
|
|
Pick 5 tracks from `conductor/archive/` or `conductor/tracks/` (use `manual-slop_list_directory`). For each:
|
|
- Read its `plan.md` and `spec.md`
|
|
- Compare the actual workflow followed (commits, tests, checkpoint) to what `workflow.md` prescribes
|
|
- Note any drift: did the track skip a phase? Add a step that isn't in `workflow.md`? Skip a verification step?
|
|
|
|
- [ ] **Step 3.4: Update `workflow.md` to match actual practice**
|
|
|
|
If a phase is being consistently skipped, either (a) update the docs to make it optional, or (b) flag the drift and ask the user. Default: (a) — update the docs to match reality, then enforce via a future lint script (which is out of scope for this track).
|
|
|
|
- [ ] **Step 3.5: Update the Phase Completion Verification section**
|
|
|
|
Verify the protocol description matches the actual steps in recent tracks. Update if needed.
|
|
|
|
- [ ] **Step 3.6: Update the Commit Guidelines section**
|
|
|
|
Verify the message format examples match recent commits. Run `git log --oneline -20` to see the recent style.
|
|
|
|
- [ ] **Step 3.7: Validate all cross-doc links**
|
|
|
|
- [ ] **Step 3.8: Commit per-section**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add conductor/workflow.md
|
|
git -C C:\projects\manual_slop commit -m "docs(workflow): <description>"
|
|
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Sync rationale: [drift findings and corrections]." $_ }
|
|
```
|
|
|
|
---
|
|
|
|
## Task 4: Sync `conductor/product-guidelines.md`
|
|
|
|
**Files:**
|
|
- Modify: `conductor/product-guidelines.md` (current size ~6.6K)
|
|
- Reference: `src/app_controller.py`, `src/gui_2.py`, `src/imgui_scopes.py`, `scripts/check_imgui_scopes.py`, recent track style
|
|
|
|
**Scope:** The AI-Optimized Python Style (1-space indent, no comments, type hints), Modular Controller Pattern, UI Delegation Pattern, Mandatory ImGui Verification, Structural Dependency Mapping (SDM) docstrings. These rules must match the actual code in `src/`.
|
|
|
|
- [ ] **Step 4.1: Pre-edit checkpoint**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add .
|
|
```
|
|
|
|
- [ ] **Step 4.2: Read the current `conductor/product-guidelines.md`**
|
|
|
|
- [ ] **Step 4.3: Spot-check the style claims against actual `src/` code**
|
|
|
|
For each style rule, sample 3 random files in `src/` and verify the rule is followed:
|
|
- **1-space indentation:** Use `manual-slop_get_file_slice` on a few files, look for any 4-space or tab-indented lines
|
|
- **No comments:** Use `grep` (via `manual-slop_run_powershell`) to find `#` characters in `src/*.py` (excluding shebangs, type comments, etc.)
|
|
- **Type hints:** Sample a few public function signatures
|
|
- **Modular Controller Pattern:** Check `src/app_controller.py` for module-level functions
|
|
- **UI Delegation Pattern:** Check `src/gui_2.py` for `render_xxx` module-level functions
|
|
- **SDM docstrings:** Check 3 random functions for `[C: ...]` and `[M: ...]` tags
|
|
|
|
- [ ] **Step 4.4: Update the guidelines to match reality**
|
|
|
|
If a rule is no longer followed:
|
|
- Option (a): Update the rule to be more accurate
|
|
- Option (b): Flag the drift and ask the user
|
|
|
|
Default: (a) — but flag any major drift in the commit message so the user is aware.
|
|
|
|
- [ ] **Step 4.5: Verify the Mandatory ImGui Verification claim**
|
|
|
|
Check that `scripts/check_imgui_scopes.py` exists and works. If it's been replaced by `src/imgui_scopes.py` and a different linter, update the docs.
|
|
|
|
- [ ] **Step 4.6: Validate all cross-doc links**
|
|
|
|
- [ ] **Step 4.7: Commit per-section**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add conductor/product-guidelines.md
|
|
git -C C:\projects\manual_slop commit -m "docs(guidelines): <description>"
|
|
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Sync rationale: [style drift findings, corrections made]." $_ }
|
|
```
|
|
|
|
---
|
|
|
|
## Task 5: Update `conductor/index.md`
|
|
|
|
**Files:**
|
|
- Modify: `conductor/index.md` (current size 334 bytes)
|
|
- Reference: every file in `conductor/`
|
|
|
|
**Scope:** The conductor directory index. Must link to all major conductor files.
|
|
|
|
- [ ] **Step 5.1: Pre-edit checkpoint**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add .
|
|
```
|
|
|
|
- [ ] **Step 5.2: Inventory `conductor/` directory**
|
|
|
|
Use `manual-slop_get_tree path="C:\projects\manual_slop\conductor" max_depth=2`.
|
|
|
|
- [ ] **Step 5.3: Identify any major conductor file not linked from `index.md`**
|
|
|
|
Likely candidates: `conductor/code_styleguides/`, `conductor/fix_test_suite_failures_20260516.md`, any new top-level files.
|
|
|
|
- [ ] **Step 5.4: Update `index.md` to link the missing files**
|
|
|
|
- [ ] **Step 5.5: Validate all cross-doc links**
|
|
|
|
- [ ] **Step 5.6: Commit**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop add conductor/index.md
|
|
git -C C:\projects\manual_slop commit -m "docs(conductor): update index with [list of newly-linked files]"
|
|
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Added links to [list]." $_ }
|
|
```
|
|
|
|
---
|
|
|
|
## Task 6: Sub-Track 2 Verification
|
|
|
|
- [ ] **Step 6.1: Dep coverage audit**
|
|
|
|
For every Python dep in `pyproject.toml`, confirm it appears in `conductor/tech-stack.md`. Use:
|
|
|
|
```powershell
|
|
$deps = (Get-Content C:\projects\manual_slop\pyproject.toml | Select-String '^\s*"?[a-zA-Z][a-zA-Z0-9_-]*[><=~]' | ForEach-Object { ($_.ToString().Trim() -split '["><=~]')[0].Trim() } | Sort-Object -Unique)
|
|
foreach ($dep in $deps) { if (-not (Select-String -Path C:\projects\manual_slop\conductor\tech-stack.md -Pattern $dep -SimpleMatch -Quiet)) { Write-Host "MISSING: $dep" } }
|
|
```
|
|
|
|
- [ ] **Step 6.2: Module coverage audit**
|
|
|
|
For every `.py` file in `src/`, confirm it appears in `conductor/tech-stack.md` or `conductor/product.md`. Use:
|
|
|
|
```powershell
|
|
Get-ChildItem C:\projects\manual_slop\src\*.py | ForEach-Object { $name = $_.BaseName; if (-not (Select-String -Path C:\projects\manual_slop\conductor\tech-stack.md, C:\projects\manual_slop\conductor\product.md -Pattern $name -SimpleMatch -Quiet)) { Write-Host "MISSING: $name" } }
|
|
```
|
|
|
|
- [ ] **Step 6.3: Feature claim verification**
|
|
|
|
For 3 random features claimed in `conductor/product.md`, verify each has a corresponding module and that the module does what the claim says. Use `manual-slop_get_file_summary` on the relevant module.
|
|
|
|
- [ ] **Step 6.4: Per-file commit verification**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop log --oneline -- conductor/product.md conductor/product-guidelines.md conductor/tech-stack.md conductor/workflow.md conductor/index.md | head -20
|
|
```
|
|
|
|
Confirm every file has its own commit history (not batched).
|
|
|
|
- [ ] **Step 6.5: Git note verification**
|
|
|
|
```powershell
|
|
git -C C:\projects\manual_slop log --format="%H" -- conductor/ | Select-Object -First 20 | ForEach-Object { $note = git -C C:\projects\manual_slop notes show $_ 2>$null; if (-not $note) { Write-Host "MISSING NOTE: $_" } }
|
|
```
|
|
|
|
- [ ] **Step 6.6: Phase completion checkpoint**
|
|
|
|
Per the project's Phase Completion Verification protocol in `conductor/workflow.md`:
|
|
- Run the automated test suite (or at least smoke tests)
|
|
- Present the verification report to the user
|
|
- Get user sign-off
|
|
- Create the checkpoint commit: `conductor(checkpoint): Sub-Track 2 (conductor docs refresh) complete`
|
|
- Attach the verification report as a git note
|
|
|
|
---
|
|
|
|
## Self-Review (after writing this plan)
|
|
|
|
1. **Spec coverage:** Spec §5 has 6 phases (2.1-2.6). Tasks 1-5 cover 2.1-2.5. Task 6 covers 2.6 (verification). ✓ All phases covered.
|
|
2. **Placeholder scan:** No "TBD" / "TODO" markers. Specific file paths, commit commands, and verification scripts throughout. ✓
|
|
3. **Type/symbol consistency:** Module names and dep names referenced consistently. The audit scripts in Task 6 are concrete and runnable. ✓
|
|
4. **Risk check:** Pre-edit checkpoints, per-file commits, git notes, and the audit scripts mitigate drift. The optional-vs-mandatory decision in Step 3.4 is flagged for the user. ✓
|