imMamdouhaboammar/anti-slop-engineering / skills/cognitive-load-and-attention-governor
cognitive-load-and-attention-governor
VerifiedEnforce cognitive bandwidth and attention economy invariants across AI agent outputs, human-in-the-loop interactions, pull request descriptions, standalone deliverables, and multi-agent swarm handoffs. Governs scannability metrics (time-to-point, max wall length, landing anchor density), terminal blocking-question placement, deliverable purity (zero opener/closer fluff), working memory list bounding (Miller's law <= 5), and non-regression constraint preservation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| examples/attention-budget-record.json | config | 853 B |
| examples/pure-deliverable-sample.md | markdown | 300 B |
| playbooks/agent-to-agent-swarm.md | markdown | 2.0 KB |
| playbooks/human-agent-interaction.md | markdown | 2.7 KB |
| references/attention-metrics.md | markdown | 3.7 KB |
| references/handoff-contracts.md | markdown | 5.2 KB |
references/handoff-contracts.md
View on GitHub# Inter-Module Handoff Contracts
This specification defines the explicit bidirectional handoff contracts between the Cognitive Bandwidth & Attention Economy Governor and existing agent engines and guard systems.
---
## 1. Handoff Contract: Attention Governor $\longleftrightarrow$ Fable Lifecycle (`get-fable`)
### Context:
Fable orchestrates complex autonomous engineering cycles (Discovery, Planning, Execution, Verification, Learning). Subagents reporting back to the coordinator emit verbose narrative tokens that inflate context windows and bury critical invariant failures.
### Ingress Contract (Subagent $\rightarrow$ Attention Governor):
When a Fable subagent finishes a task or hits a circuit breaker, its raw markdown report must pass through the Attention Governor filter before submission to the orchestrator:
```toon
[SubagentHandoffEnvelope] (version: 1.0)
fields: 5
task_id: string
execution_phase: enum(DISCOVERY|PLANNING|EXECUTION|VERIFICATION|LEARNING)
status_checklist: list[4] (done, in_progress, not_started, unknown)
blocking_decision: optional[BlockingAsk]
state_payload: string
```
### Filtering Invariants:
1. **Rundown State Checklists:** State must be rendered strictly with 4 standard indicators:
- `✅ <subject> <past-tense-verb>`
- `🟡 <subject> <present-participle-verb>`
- `⬜ <subject> not started`
- `❔ <subject> unknown`
2. **Terminal Blocking Placement:** If `blocking_decision` is present, it MUST be positioned at the terminal block of the TOON envelope, and Line 1 must declare: `FLAG: Decision required before phase transition.`
3. **Purity Enforcement:** Zero transitional conversational filler ("I have completed the tasks you assigned me. Here is the summary...").
---
## 2. Handoff Contract: Attention Governor $\longleftrightarrow$ Latent Workspace (`j-space`)
### Context:
J-Space (Gurnee et al., Anthropic 2026) models the internal representations of concepts an agent is "poised to say". Unfiltered dumping of internal deliberations creates conversational slop.
### Egress Contract (J-Space $\rightarrow$ External Transcript):
1. **The Poised-to-Speak Filter:** Deep multi-turn internal reasoning, backtracking, and counterfactual proofs remain bounded inside J-Space internal memory.
2. **The Broadcast Gate:** When materializing tokens to the external conversation transcript:
- Apply the **Bottom-Line Rule:** The single most decisive verdict or architectural conclusion occupies Line 1.
- Apply **Anchor Injection:** Break homogeneous reasoning into blank-line-separated points with bold anchors (`**Takeaway.**`) or directional arrows (`→`).
- Suppress Tangents: Speculative design musings that do not affect the immediate task are retained in J-Space rather than emitted.
---
## 3. Handoff Contract: Attention Governor $\longleftrightarrow$ Autonomous Review (`openreview` & `omni-skill`)
### Context:
OpenReview and OmniSkill post automated PR review comments, suggestions, and architectural triage reports across GitHub, GitLab, and local IDEs.
### Ingress & Egress Invariants:
1. **100% Deliverable Purity:**
$$\mathcal{P}_{deliv} = 1.0$$
Automated comments must never begin with "I noticed that..." or "Good job on this PR, however...".
2. **Direct Suggestion Format:**
Reviews must lead immediately with the target file and line anchor:
```markdown
**`src/auth.ts:42`** Replace deprecated token verification with crypto-safe validator.
```diff
- const token = jwt.verify(raw);
+ const token = await safeVerifyToken(raw, { maxAge: 3600 });
```
```
3. **Miller's Law Review Cap:**
A single review pass must present at most 5 top-priority findings per review comment. Additional findings must be grouped into expandable sections or deferred to subsequent triage passes.
---
## 4. Handoff Contract: Attention Governor $\longleftrightarrow$ PR Boundary & Comment Budget Guards
### Integration Matrix:
| Guard | Primary Domain | Attention Governor Cross-Validation |
|:------|:---------------|:------------------------------------|
| `pr-boundary-guard` | Git provenance, branch naming, template checkboxes, commit subjects | Audits the PR description body for Time-to-Point ($TTP \le 20$), Maximum Wall Words ($W_{max} \le 60$), and terminal question placement. |
| `comment_budget_guard` | Comment-to-Code Ratio ($\text{CCR} \le 0.35$), banning syntax play-by-play | Ensures retained comments are concise, load-bearing contracts with zero cognitive fluff. |
| `diff_guard` | Seven Gates, SRE rules, AST rules, sensitive secrets | Scans newly added markdown files, READMEs, and docstrings for opener wrappers and closer offers. |
---
## 5. Handoff Contract: Attention Governor $\longleftrightarrow$ Audit Runner (`scripts/audit_runner.py`)
### Execution Protocol:
During `bunx anti-slop-engineering check` or `bunx anti-slop-engineering audit`:
1. `attention_guard` executes against modified markdown files and PR diffs.
2. Any `blocker` finding (`COGNITIVE-BURIED-ASK`, `COGNITIVE-DELIVERABLE-IMPURITY`, `ERR_EXCESSIVE_WALL_OF_TEXT`) triggers exit code 2 and blocks CI / automated pull request merges.
3. Machine-readable findings are formatted as RFC 9457 Problem Details in the compiled audit report (`anti-slop/audit-NNN.md`).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |