Skip to content

AI usage coach — removal

Ticket #246: Removal of the AI usage coach agent
Type: Automation / Workflow / Governance
Affected Component: .github/agents/ai-coach.agent.md, .github/ai-coach.config.json, .github/hooks/ai-coach-session-start.json, .github/prompts/ai-coach-report.prompt.md, scripts/hooks/ai_coach_session_start.ps1, scripts/hooks/ai_coach_append_event.ps1, tests/test_ai_coach_infrastructure.py

1. Context and decision

The AI usage coach was introduced in two successive iterations — tickets #224 and #232 — with the goal of analyzing GitHub Copilot work sessions, measuring token pressure, and producing targeted coaching reports to improve prompting habits.

After operating the system through multiple sessions, two structural problems became clear:

1 — Insufficient metric quality

Despite the hardening work done in ticket #232, the event collection remained too thin to produce genuinely useful session evaluations. The coach could confirm that a session had started, but struggled to reconstruct what had actually happened during it, what the objective was, what actions had been taken, and what the outcome was. The reports it generated were too superficial to inform real behavior change.

2 — Non-negligible token cost

The coach's activation infrastructure — startup hooks, event files, configuration files, and report prompts — added context load at every session. This overhead worked directly against the core objective the agent was designed to serve: reducing token waste. The tool was consuming the very resource it was meant to optimize.

Given these two findings, the decision was made to remove the agent entirely rather than invest in a third iteration of uncertain return.

2. What was removed

Seven files were deleted:

File Purpose
.github/agents/ai-coach.agent.md Agent definition and behavior instructions
.github/ai-coach.config.json Central configuration (capture mode, retention settings)
.github/hooks/ai-coach-session-start.json Hook declaration for session startup
.github/prompts/ai-coach-report.prompt.md Report generation prompt
scripts/hooks/ai_coach_session_start.ps1 Startup hook — session ID generation and artifact creation
scripts/hooks/ai_coach_append_event.ps1 Checkpoint writing hook
tests/test_ai_coach_infrastructure.py Non-regression tests for the coach infrastructure

3. What was kept

The three activity reports documenting the design decisions, the technical implementation, and the problems encountered are preserved as institutional memory:

This documentation ensures that if the problem resurfaces in the future, the rationale for each architectural choice and each failure point is traceable without having to reconstruct it from scratch.

4. Outcome

All 123 automated tests continued to pass after the deletion. No functional dependency on the coach infrastructure existed in the rest of the codebase. The removal was clean, reversible through version control, and committed to branch ai-agent-coach-deletion.