| name | using-cogitation |
| description | Use at the start of any conversation — establishes the cogitation workflow and requires invoking the right skill before responding, including before clarifying questions |
If you were dispatched as a subagent to execute a specific task, skip this skill and do the task.
If there is even a 1% chance a cogitation skill applies to what you're doing, CHECK for it BEFORE responding — including before clarifying questions. Checking now includes **sizing** (see "Size before routing") — it does not mean brainstorming for everything. If the skill turns out to be wrong, you can drop it. Knowing the concept is not the same as using the skill.
Using Cogitation
Cogitation is an opinionated development workflow backed by Engram Cogitator (EC) persistent memory. Skills carry the discipline; EC carries the memory across sessions.
Instruction Priority
- User instructions (CLAUDE.md, direct requests) — always win.
- Cogitation skills — override default behavior where they conflict.
- Default system prompt — lowest.
If CLAUDE.md says "don't use TDD" and a skill says "always," the user wins.
How to Access Skills
Use the Skill tool — it loads the skill content for you to follow. Never Read a skill file instead of invoking it. Skills evolve; don't run from memory.
Size before routing
Before routing any build/change request, size it and announce the sizing
aloud — Sizing: <tier> — <reason>. The announcement is the license to take
a lighter path; silent skipping is the violation.
| Tier | Test | Route |
|---|
| TRIVIAL | no behavior change — typo, rename, comment, config value, doc edit | just do it, verify after |
| SMALL | behavior-preserving fix / tiny addition; two-way door (easily undone, no new behavior surface, no data/API/schema change) | tdd / debugging |
| MEDIUM | new behavior but contained — one component, no arch/data/API change | sketching (half-page combo doc) |
| FULL | new behavior surface, one-way door, arch/data/API | brainstorming → writing-plans |
- Torn between tiers → pick the heavier.
- Scope grows mid-flight (one-way door, new dependency, second component) →
STOP, announce the re-size, escalate with context in hand.
- User vetoes a sizing →
ec_add a learning (area: workflow/triage) so
calibration improves.
The Workflow
sizing → brainstorming → writing-plans → executing-plans → finishing-branch
│ (FULL)
└→ sketching (MEDIUM) · tdd/debugging (SMALL) · just do it (TRIVIAL)
│
@tdd ·@debugging ·@verifying ·review ladder
Pick the entry point by intent:
| You're about to… | Invoke |
|---|
| Build a feature / change behavior / "let's add X" | size it first — brainstorming (FULL) or sketching (MEDIUM) |
| Turn an approved design into tasks | writing-plans |
| Implement an existing plan | executing-plans (continuous TDD) |
| Write any code | tdd (red → green → refactor) |
| Chase a bug | debugging |
| Claim something is done | verifying |
| Get review on a diff | requesting-review (Tier 1) → @receiving-review |
| Wrap up / merge | finishing-branch |
| Remember a decision/gotcha | remember |
| Onboard to a repo | onboard · init (first-time setup) |
| Tailor the workflow / change how strict it is | customising |
Process skills before implementation skills. "Build X" → size, then brainstorming or sketching. "Fix bug" → debugging first.
Workflow posture
When the SessionStart hook injects an "Active workflow posture" block, apply
those per-skill overrides when routing: a DISABLED skill is not routed to;
an advisory skill's discipline is recommended, not mandatory. User
instructions still win (see Instruction Priority).
EC memory is part of the loop
Skills search EC (ec_search) for prior decisions/patterns/learnings before acting, and store (ec_add) durable ones after. If EC isn't running, skills degrade gracefully — proceed without it.
Graphify (optional, strict when on)
If .cogitation/config.json has graphify.enabled: true, structural code questions ("what calls X", "where does Y live") go through graphify query as a required recon step in onboard/brainstorming — not optional. If disabled, skip graphify entirely.
Red Flags — these thoughts mean STOP, you're rationalizing
| Thought | Reality |
|---|
| "This is just a simple question" | Questions are tasks. Check for a skill. |
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
| "I'll just do this one thing first" | Check BEFORE doing anything. |
| "I'll skip the sizing announcement" | The announcement IS the license. Skipping silently is the violation. |
| "It's still small" (as scope grows) | Growth is a re-size. Announce it and escalate. |
| "I remember this skill" | Skills evolve — invoke the current version. |
| "No production code without a failing test… but just this once" | No. @tdd is rigid. |
Skill Types
Rigid (tdd, debugging, verifying): follow exactly — don't adapt away the discipline.
Flexible (patterns, onboarding): adapt principles to context. The skill says which it is.
