tdmcp-implementation-learning - post-implementation learning harness

Coordinate a focused study of a completed tdmcp implementation, then turn the evidence into a prioritized improvement backlog. This harness answers: "What did this implementation teach us, and what should tdmcp improve next?"

Use it after a feature has already been built, merged, tested in TouchDesigner, used with hardware, reviewed in a PR, or exercised in a real installation.

Boundary

This harness studies and routes improvements. It does not own arbitrary feature implementation.

• Shipped/merged implementation learning: tdmcp-implementation-learning.
• Chosen new feature build: tdmcp-pipeline.
• Broad repo quality or command health: tdmcp-quality-audit.
• Known coverage gaps: tdmcp-test-coverage.
• Docs, roadmap, or changelog sync: tdmcp-docs-roadmap-update.
• Continued Kinect wall harp work: tdmcp-kinect-wall-harp.

Execution mode: sub-agent fan-out -> fan-in

No TeamCreate. Use coordinated sub-agents with file handoffs.

• Scope: lead only. Determine target feature, evidence sources, and artifact directory.
• Study: sub-agent fan-out. Code, runtime, and quality surfaces can be inspected independently.
• Synthesis: one sub-agent. One owner dedupes findings and ranks next actions.
• Handoff: lead only. The user gets a compact decision-ready report.

All agent calls use model: "opus" unless the caller has a stricter local policy.

Agent roster

• tdmcp-implementation-learning-lead: _workspace/implementation-learning/<slug>/00_scope.md and final handoff.
• tdmcp-implementation-cartographer: _workspace/implementation-learning/<slug>/01_map.md.
• tdmcp-implementation-runtime-analyst: _workspace/implementation-learning/<slug>/02_runtime_lessons.md.
• tdmcp-implementation-quality-analyst: _workspace/implementation-learning/<slug>/03_quality_gaps.md.
• tdmcp-implementation-synthesizer: _workspace/implementation-learning/<slug>/04_backlog.md.

Use a short slug from the implementation name or PR, for example kinect-wall-harp, ai-party-mixer-scene, or pr-114-external-kinect.

Workflow

Phase 0 - context and safety check

1. Read the current repo state with git status --short --branch.
2. Read CLAUDE.md and any feature-specific harness pointer that already exists. Prefer extending or routing through existing harnesses over inventing overlapping ones.
3. Identify the implementation being studied from the user's request. If it is ambiguous, infer the most recent relevant feature from local context and state the assumption.
4. Create _workspace/implementation-learning/<slug>/.
5. Write 00_scope.md with:
   • target implementation and date/context
   • source branches, PRs, docs, specs, tools, scripts, and generated artifacts
   • live/hardware evidence that exists or is missing
   • explicit exclusions
6. Preserve unrelated user changes. Do not revert or clean generated files unless the user specifically asks.

Phase 1 - parallel study

Run the three analyst agents in parallel when their scopes are independent. Each writes incrementally to its artifact file.

Cartographer scope

Map the implementation across code, docs, CLI, tests, recipes, bridge scripts, runtime helpers, and generated TouchDesigner project structure.

Required output fields:

• shipped surfaces
• data/control flow
• coupling points
• reusable patterns
• duplicated or one-off code that could become a common primitive
• missing ownership boundaries
• follow-up candidates with file references

Runtime analyst scope

Study the implementation from the user's real usage path: TouchDesigner bridge, Kinect/camera/audio/projector setup, diagnostics, calibration, failure modes, latency, and operator ergonomics.

Required output fields:

• what was actually verified live
• what remains UNVERIFIED
• user pain points observed during the implementation
• runtime diagnostics that helped or were missing
• setup steps that should become tool affordances or docs
• hardware assumptions that should be explicit

Do not report hardware or TouchDesigner checks as passing unless they were actually run.

Quality analyst scope

Study the implementation for tests, CI, review feedback, validation gaps, warnings, script robustness, security, and maintainability.

Required output fields:

• current gates checked
• failing or unverified gates
• regression risks
• missing unit/integration/bridge/live tests
• review findings that should become tests or lint checks
• safe first patch candidates

Phase 2 - synthesis

Spawn tdmcp-implementation-synthesizer. It reads 00_scope.md, 01_map.md, 02_runtime_lessons.md, and 03_quality_gaps.md, then writes 04_backlog.md.

The backlog must group items by action type:

• CODE
• TEST
• DOCS
• RUNTIME
• HARNESS
• RESEARCH

Each item must include:

• title
• evidence
• proposed change
• target files or harness
• impact: High, Medium, or Low
• effort: S, M, or L
• confidence: High, Medium, or Low
• recommended route: direct patch, tdmcp-pipeline, tdmcp-quality-audit, tdmcp-test-coverage, tdmcp-docs-roadmap-update, or feature-specific harness

Phase 3 - QA and handoff

The lead reads all artifacts and performs a consistency pass:

1. Every claim has evidence or is clearly marked UNVERIFIED.
2. Items already present in docs/ROADMAP.md are labeled as roadmap extensions, not rediscovered work.
3. Findings are not duplicate entries under different names.
4. Recommended immediate work is small enough for a first patch wave.
5. The final response names artifact paths, top priorities, unverified areas, and the next build route.

If the user asked to continue beyond study, the lead can start the first safe wave after synthesis:

• docs-only improvements -> apply directly or route to tdmcp-docs-roadmap-update
• missing tests -> route to tdmcp-test-coverage
• feature implementation -> route to tdmcp-pipeline
• live Kinect/wall harp continuation -> route to tdmcp-kinect-wall-harp
• repo-wide health -> route to tdmcp-quality-audit

Output format

Use this artifact tree:

_workspace/implementation-learning/<slug>/
  00_scope.md
  01_map.md
  02_runtime_lessons.md
  03_quality_gaps.md
  04_backlog.md
  05_qa.md

The final user-facing summary should stay concise:

• target studied
• top 3-5 improvements
• what is ready for a first patch wave
• what remains unverified
• artifact path

Error handling

• Feature scope is unclear: infer from branch/context, state the assumption, and keep scope editable.
• Live hardware is unavailable: continue code/docs/test study and mark runtime checks UNVERIFIED - hardware not available.
• Prior artifacts exist: read them first and resume/update only the requested section.
• Analyst output is missing or thin: re-run that analyst once; otherwise synthesize with a coverage gap.
• Finding requires a new feature: route it; do not silently build it inside the learning harness.
• Finding conflicts with existing roadmap: label as ROADMAP or EXTENSION with citation.

Test scenarios

Normal: user asks to study the Kinect wall harp implementation after merge. Lead creates _workspace/implementation-learning/kinect-wall-harp/, scopes code and PR evidence, runs cartographer/runtime/quality analysts in parallel, synthesizer writes a ranked backlog, and lead recommends a first patch wave: for example bridge robustness, sensor diagnostics, calibration UX, reusable physical-installation docs, and missing regression tests.

Scoped: user asks only for "what did the audio problem teach us?" Lead scopes kinect-wall-harp-audio, runs cartographer and quality analyst only if runtime artifacts already explain the issue, synthesizes a short backlog around audio device/sample-rate diagnostics, gain staging, and testable synth defaults.

Unavailable hardware: user asks to learn from a physical installation but TouchDesigner/Kinect is not connected. The runtime analyst records setup questions and UNVERIFIED checks, while code/docs/quality reports still produce actionable improvements.