GCarin1GCarin1/Doctrina/.agents/skills/split-an-oversized-spec/SKILL.md

split-an-oversized-spec

Skill1 starsChanged 10 days agoMITView on GitHub

Split a capability spec that crossed the 400-line cap into two coherent capabilities without losing provenance. Use when: doctrina validate warns that a spec exceeds the 400-line soft cap, or a spec accretes a second responsibility.

In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/00-doctrina.mdcCursor rule
- add-cli-commandSkill
- cut-a-releaseSkill
- keep-docs-en-pt-paritySkill
- ledger-abandoned-entries-are-ledger-onlySkill
- patch-doctrina-files-as-crlfSkill
- read-the-grammar-through-the-document-modelSkill
- stage-a-change-backlogSkill
- triage-holds-work-on-the-machinerySkill
- write-acceptance-evidenceSkill
- add-cli-commandSkill
- cut-a-releaseSkill
- keep-docs-en-pt-paritySkill
- ledger-abandoned-entries-are-ledger-onlySkill
- patch-doctrina-files-as-crlfSkill
- read-the-grammar-through-the-document-modelSkill
- split-an-oversized-specSkill
- stage-a-change-backlogSkill
- triage-holds-work-on-the-machinerySkill
- write-acceptance-evidenceSkill
- doctrina-contextSkill
- doctrina-nextSkill
- doctrina-statusSkill
- doctrina-whySkill
- doctrina-workSkill

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Do not compress prose to sneak under the cap — split along a responsibility seam.
line 16
Very specific:
Create the new spec folder and file by hand or via doctrina spec new <new-cap>.
line 23
Very specific:
Update anything that counts specs (README.md, README.pt.md) and run the gates: validate (cap warning gone), trace (anchors intact), …
line 40

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

<!-- doctrina:skill-export — generated from .doctrina/skills/split-an-oversized-spec.md by `doctrina index rebuild`; edit that file, not this one. -->

Skill — split-an-oversized-spec

When to use this skill

doctrina validate warns spec.md is NNN lines (>400 soft cap).
A spec's Event-driven section reads as two unrelated clusters.

Procedure

Do not compress prose to sneak under the cap — split along a responsibility seam. (Precedent: cli 551 lines → cli 399 + gates 227, 2026-07-02.)

Find the seam: group the Event-driven requirements by theme and pick the largest coherent cluster that names a capability on its own (for cli it was "gate/insight command semantics").
Create the new spec folder and file by hand or via doctrina spec new <new-cap>; give it real headers: Status, Implementation (match reality), Realizes: (an [SCn] anchor or a deliberate n/a — <why> so doctrina trace stays green).
MOVE the requirement blocks verbatim — do not rewrite EARS prose while moving (one change, one intent). Keep each section's EARS grammar intact so the validate shape check stays quiet.
Give the new spec its own ## Acceptance criteria with resolving evidence (see the write-acceptance-evidence skill); move any criterion that belongs to the moved cluster and renumber what remains in the source spec.
In the source spec: add a one-line pointer in ## Purpose and an ## Out of scope bullet naming the new capability; in the new spec: point back the same way. No fact may live in both files.
doctrina spec set <old-cap> --bump minor — it stamps Last updated and rebuilds index.json, registering the new spec in the same pass.
Update anything that counts specs (README.md, README.pt.md) and run the gates: validate (cap warning gone), trace (anchors intact), coverage --strict (both specs cite proof).

Anti-patterns

Deleting requirements to fit the cap — the cap is a reading budget, not permission to lose the contract.
Splitting by grammar section (all Event-driven here, the rest there) instead of by responsibility: both halves stay incoherent.
Forgetting Realizes: on the new spec — it becomes the only untraceable capability and trace --strict goes red.

Related material

.doctrina/specs/cli/spec.md and .doctrina/specs/gates/spec.md — the executed example.
ADR 0007 (structured spec deltas); ADR 0009 (index resync).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free