---
name: dialectic-of-cognition
description: >
  Evaluate whether this session warrants rule updates — either from complex
  debugging learnings or from structural code changes that shift patterns
  the rules should encode. Invoke manually at end of session; never auto-trigger.
disable-model-invocation: true
allowed-tools: Bash, Read, Grep, Glob, Edit, Write
---

‼️ REMOVE THIS WHOLE FIRST SECTION
Any lines that say 💡 SETUP_NOTE should be replaced with your local configuration and the line removed.

- 💡 SETUP_NOTE: Place this file at `.claude/skills/dialectic-of-cognition/SKILL.md`.
- 💡 SETUP_NOTE: This skill assumes your project has `.cursor/rules/general.mdc` with the **Rule Maintenance (Self-Evolving Rules)** section and a **routing table** (use the companion `general.mdc` from this gist), plus one or more domain `.cursor/rules/*.mdc` files.
- 💡 SETUP_NOTE: If you haven't set this up yet, copy `general.mdc` from this gist into `.cursor/rules/general.mdc` and customize the routing table.

‼️ REMOVE THIS WHOLE FIRST SECTION

---

# /dialectic-of-cognition — Capture session learnings into evolving rules

You are performing rule maintenance per the **Rule Maintenance (Self-Evolving
Rules)** section of `.cursor/rules/general.mdc`. Read that section in full
before proceeding — it is the authoritative process (dialectic of cognition:
particular → general → particular). What follows is the operational harness;
the rules file defines the principles.

This command has two modes. Determine which applies, or run both if the
session had both complex debugging and structural code changes.

---

## Mode A — Debugging learnings (original dialectic)

Use this mode when the session involved hard bugs: non-obvious root causes,
multiple corrective attempts, external documentation consulted, or debugging
that took >5 minutes.

### Phase A0 — Triage: did a debugging session happen?

Scan the session transcript for the triggers defined in the rules file:

- Debugging took >5 minutes
- External documentation was consulted
- More than one corrective attempt was needed before the fix worked
- The root cause was non-obvious from the error message alone

**If none fired:** state "Mode A: no debugging triggers — skipping." and move
to Mode B. Do not fabricate learnings. Trivial fixes (typos, config values,
one-line renames) do not qualify.

### Phase A1 — Extract (Particular → General)

For each qualifying trigger, extract the **class** of problem, not the instance:

1. Identify the **symptom**: what did the user/AI observe first?
2. Identify the **root cause pattern**: what general mechanism produced this class of failure?
3. Identify the **resolution pattern**: what general action resolved it?

Discard session-specific details (timestamps, file paths, exact error strings
unless they're the diagnostic signature). Keep the pattern.

### Phase A2 — Route (which rule file?)

Use the routing table at the bottom of the Rule Maintenance section in
`general.mdc` to determine which `.cursor/rules/*.mdc` file(s) should receive
each learning.

---

## Mode B — Code change → rule impact (structural)

Use this mode after ANY non-trivial session that changed code. The question
is not "what did we debug?" but "do these code changes alter, extend, or
invalidate any patterns encoded in the rules files?"

### Phase B0 — Summarize what changed

Scan the git diff and session context. List:

- New files created (packages, components, handlers)
- Existing files modified and the nature of the change (new feature, refactor, config)
- Any new patterns introduced (e.g., a new pipeline type, a new component family)

### Phase B1 — Check the routing table

Open the routing table in `general.mdc`. For each change, identify which rule
file governs that domain:

| Change                                         | Domain                       | Rule file        |
| ---------------------------------------------- | ---------------------------- | ---------------- |
| New data pipeline wired into unified scheduler | Service architecture, ingest | `<services>.mdc` |
| New report fields                              | Service architecture         | `<services>.mdc` |
| New env vars                                   | Service config               | `<services>.mdc` |

💡 SETUP_NOTE: *(The examples above use placeholder rule file names — substitute your own.)*

### Phase B2 — Read the relevant rule files

Open each rule file identified above. Scan for:

1. **Structural sections that are now stale** — e.g., "the services rule's
   Data Pipeline section says data is only available via HTTP endpoints but
   now it's also in the unified scheduler"
2. **Term definitions that need updating** — e.g., "the data flow section
   lists pipeline A + B but not the new pipeline C"
3. **Gotchas/checklists that need new entries** — e.g., "adding a new
   content type to the unified job requires touching N files"

### Phase B3 — Apply the abort gate

For each candidate update, apply the one-sentence test from the rules file:
**can you state the rule without naming a specific file, function, class,
variable, or endpoint?** If not, skip it — the change doesn't generalize.

### Phase B4 — Route and encode

Same as Mode A Phase A2, then follow the encode/verify/integrity steps from
the rules file. Prefer refining existing entries over creating new ones.

---

## Shared phases (apply to all learnings from either mode)

### Phase 1 — Encode (General → Particular)

For each learning from either mode, follow the encode step from the rules file:

1. **Scan the target file** for existing entries that overlap (same symptoms,
   same root cause, same resolution). If found, **refine the existing entry**
   (add a row, sharpen the description) — do not duplicate.
2. If the learning is genuinely novel, create a new problem class entry using
   the format prescribed in the rules file (symptom/cause/fix table).
3. Add a `<!-- last-verified: YYYY-MM -->` timestamp to every entry you touch.

### Phase 2 — Verify (practice tests theory)

For each new or modified entry, run the verification check from the rules file:

> Would the AI, reading this rule for the first time, recognize the symptom and
> apply the fix without re-investigation?

Read the symptom column. Read the cause and fix. Do they form a closed loop?
If not, refine until a cold read succeeds.

### Phase 3 — Integrity checks

Per the rules file, before finishing:

1. **Contradiction check**: scan the target file for existing entries that would
   prescribe a *different* action for the same symptoms. If found, encode the
   boundary condition — don't silently overwrite.
2. **File size check**: if the target file now exceeds 600 lines, flag it for
   the user and propose a split (suggest sub-domain and candidate file name).
   Do NOT split without user approval.
3. **Decay check**: scan entries older than 6 months in the target file. Flag
   any that look stale (code/API/architecture has changed since then).

---

## Output format

```
## Session capture — [brief session topic]

### Mode A — Debugging learnings
[Triggers found: list / "No debugging triggers — skipped"]

### Mode B — Code change → rule impact
Changes scanned:
- [change 1]
- [change 2]

### Learnings encoded
| Mode | Rule file      | Problem class / Section | Action                       |
| ---- | -------------- | ----------------------- | ---------------------------- |
| A    | <domain>.mdc   | `<class>`               | New entry                    |
| B    | <services>.mdc | Data flow section       | Added pipeline documentation |

### Integrity
- Contradictions found: none / [describe boundary condition encoded]
- File size flags: none / [file] at [N] lines — propose split
- Stale entries flagged: none / [list]

### Skipped
- [reason something was not captured]
```

If both modes found nothing: respond only with **"Nothing to capture — session was routine."**