manual_slop/docs/superpowers/plans/2026-06-02-conductor-docs-refresh.md

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

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

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

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

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

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

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

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

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

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

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:

$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:

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

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

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. ✓