| name | skill_coherence_loop |
| description | Bidirectional protocol for keeping system skills alive. Governs when to read skills as context (planning), when to update them (post-action), and how to audit them for drift (session end). |
Skill Coherence Loop
[!IMPORTANT]
This skill governs all other skills. Every significant agent action has two mandatory obligations:
- READ: Before acting on a subsystem, identify and read the skill(s) that govern it.
- WRITE: After acting, emit a Skill Harvest table and await user approval before editing any skill.
Neither phase is optional for architectural or behavioral changes.
1. The Bidirectional Contract
Skills are not static references. They are living DNA — the SSOT for how this system's subsystems work. The contract is:
User Request
→ skill_coherence_loop: route to relevant skills
→ READ relevant skills as planning context
→ Execute action
→ skill_coherence_loop: harvest findings from action
→ Emit Skill Harvest table
→ ← USER approves
→ Surgical skill edits committed
2. Manual Trigger — skill pass
The canonical invocation to explicitly run a coherence pass. Say:
| Invocation | What It Does |
|---|
skill pass | Full audit across all system skills listed in the Skill Index |
skill pass on diagnostics.log | Routes log findings → routing map → harvest table |
skill pass on Issue #N [description] | Deep-dives that issue → identifies affected skills → harvest |
skill pass on Law X.Y | Checks which skills should document that Law → spots gaps |
skill pass on [feature name] | Uses the current implementation plan as context |
skill pass on startup | Scopes audit to startup-related skills only |
Execution Steps for skill pass [on <context>]
- Identify the artifact or context provided
- Read each skill in the routing map that applies to that context
- Analyze the context against each skill's current content
- Emit the Skill Harvest table (§ 5)
- Gate — await user approval before touching any skill file
3. Automatic Flags — Passive Detectors
The agent watches for these signals during any turn. When triggered, a ⚑ Skill Flag is appended as a one-liner at the end of the response. The agent NEVER auto-edits skills — it only surfaces the flag.
Flag Format
⚑ Skill flag: [skill-name] may need updating — say 'skill pass on [context]' to proceed.
Detector A — Law or Guard Named in Code
Signal: A comment matching // Law X.Y: or // Guard: appears in a new or modified file.
Action: Flag the skill that governs that subsystem.
Example: // Law 8.1 (Neural Guard) → flag autoplay_orchestration
Detector B — Implementation Plan Executed (POST-GO)
Signal: User has said GO and the agent has completed plan execution.
Action: Auto-generate the Skill Harvest table based on the plan's changed subsystems. Emit as part of the execution summary.
Note: This is the strongest trigger — always produces a harvest table, not just a flag.
Detector C — diagnostics.log Analyzed
Signal: A diagnostics.log file is provided as context AND the agent categorizes issues from it.
Action: Auto-build the issue-to-skill routing table as part of the analysis response.
Example: Issue #3 (cache count always 0) → flag state_coherence_v4 and system_context
Detector D — New IPC Message Type or State Field Added
Signal: A new MessageType enum value, top-level store field, or architectural boundary is introduced in source.
Action: Flag system_context Skill Index as potentially stale.
Detector E — Planning Mode Entry
Signal: Agent begins writing an implementation_plan.md.
Action: Agent silently reads all relevant skills as context before formulating the plan. No notification to user — this is the invisible READ phase.
Detector F — Session Summary Requested
Signal: User says "summarize", "wrap up", "end session", "prepare handoff", or similar.
Action: Auto-run the full Skill Coherence Audit (§ 6). Always produces a Skill Delta Report. Always gates on user approval before edits.
4. Skill Routing Map
Maps a finding's domain to the primary skill that should document it.
| Finding Domain | Primary Skill | Secondary Skill |
|---|
| Neural warm-up / re-init / cold-start | startup_orchestration | system_context |
| Pre-fetch races / lock contention / segment abort | autoplay_orchestration | — |
| Cache miss / manifest divergence / count=0 bug | state_coherence_v4 | system_context |
| Dedup guards / synthesisStarting / intentId | read_aloud_injection_guard | state_coherence_v4 |
| IPC flooding / UI_SYNC storms / voice list size | state_auditor | system_context |
| Playback laws / new guards baked in source | autoplay_orchestration | — |
| Rate / pitch / audio corruption | autoplay_orchestration | — |
| DPG / Pulse logic / boot sequence | startup_orchestration | — |
| Log patterns / shorthand / density | log_sanitization_v3 | — |
| Engine mode switching (neural/local) | system_context | autoplay_orchestration |
| Session/turn metadata / extension_state.json | session_persistence | — |
| Memory leaks / listener accumulation | lifecycle_guard | — |
| Release / packaging / changelog | release_prestige | version_sentinel |
| New subsystem / renamed file / architectural map change | system_context | — |
5. Post-Action Harvest Gate (Mandatory Format)
After any triggering action, emit this table. Do NOT edit skills until user approves.
## 🔬 Skill Harvest
| Skill | Trigger | Update Type | Summary of Change |
|---|---|---|---|
| startup_orchestration | Pulse 2 fires twice | ADD | DPG idempotency guard — fired flag must survive focused_updated events |
| autoplay_orchestration | Segment Aborted on pre-fetch | AMEND | Window=5 causes lock starvation in neural pipe |
| system_context | Cache count always 0 | ADD | Bridge manifest divergence: isFullSync not updating extension host |
Update Taxonomy
| Type | Meaning |
|---|
| ADD | New subsection: newly discovered pattern, law, or root-cause |
| AMEND | Correct an existing section that is now stale or wrong |
| REFERENCE | Insert cross-link to another skill or Law (no new content) |
| STAMP | Mark a section as superseded or deprecated |
6. Session-End Skill Coherence Audit
Runs automatically when a session summary is triggered (Detector F).
Step 1: Scan All Skills
Read every skill listed in system_context § 0.1 Skill Index.
Step 2: Staleness Check Per Skill
For each skill, check:
Step 3: Emit Skill Delta Report
## 📊 Skill Delta Report
| Skill | Status | Notes |
|---|---|---|
| autoplay_orchestration | 🔴 Stale | Missing: Law 8.1 Neural Guard |
| startup_orchestration | 🟡 Gap | Missing: Pulse 2 double-fire pattern |
| state_coherence_v4 | 🟢 Healthy | Accurate |
| system_context | 🟡 Gap | Skill Index missing skill_coherence_loop |
Step 4: Positive Progress Summary
Based on Laws added, bugs fixed, and tests added this session, narrate what improved.
This is the session heartbeat — a human-readable note about what the system knows now that it didn't before.
Format:
## ✅ Session Progress (Skill Lens)
This session extended the system's understanding in [N] ways:
- **Law 8.1 (Neural Guard)**: The system now knows that neural audio is pre-baked at the target rate.
Applying `playbackRate` on top was causing 2x–16x effective speed. This is now guarded.
- **Gate 5 Addendum**: The SyncManager now suppresses state-equivalent flushes during active playback,
eliminating ~8 redundant 150KB IPC packets per 4-second window.
Step 5: Gate
Present the Delta Report and Progress Summary. Await GO before editing any skill.
7. Skill Staleness Heuristics
A skill section is stale if any of the following are true:
- It references a file that no longer exists or was renamed
- It describes a pattern superseded by a named Law added in source
- Its snapshot date is > 2 major versions behind current
- It omits a confirmed architectural truth already present in
system_context
- A test was added this session that encodes a behavioral invariant not yet documented
