agentleFS
GCarin1GCarin1/Doctrina/.agents/skills/read-the-grammar-through-the-document-model/SKILL.md

read-the-grammar-through-the-document-model

Skill1 starsChanged 4 days agoMITView on GitHub

Read checkboxes, headers, sections and comments of a .doctrina artifact through lib/doc-model.js instead of a new regex, so every surface counts the same thing. Use when: The task adds code under packages/doctrina-cli/src/ that parses a checkbox, a list or bare-bold header, a `## ` section, or an HTML comment out of an artifact (proposal, tasks, spec, delivery, ADR).

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 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.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Look in packages/doctrina-cli/src/lib/doc-model.js first.

    line 20
  2. Very specific:

    When two surfaces report on the same boxes, make them call the SAME function.

    line 30
  3. Very specific:

    If the model genuinely lacks the shape you need, add it to doc-model.js with its test — never a private copy in the caller.

    line 36
  4. Very specific:

    Run node --test test/one-box-count.test.js before the full suite: it greps src/ for a box-state capture outside the model.

    line 38

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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/read-the-grammar-through-the-document-model.md by `doctrina index rebuild`; edit that file, not this one. -->

Skill — read-the-grammar-through-the-document-model

When to use this skill

  • A new command or a new lib function reads boxes (- [ ]), a header (- **Status:**, **Version:**), a section (## Release) or skips an HTML comment in a .doctrina/ artifact, or in a workspace delivery file.
  • A test failure names one-box-count.test.js ("the box grammar has one owner") or another ADR 0021 contract test.

Procedure

  1. Look in packages/doctrina-cli/src/lib/doc-model.js first. It owns the on-disk grammar (ADR 0021): parseChecklist(text, { section }) and checklistProgress for boxes (every bullet marker, -, *, +, and placeholders), readHeader / getHeader / setHeader for both header styles, getSection / listSections for sections, maskComments / commentRanges to skip a comment by position.
  2. Compose them instead of re-deriving them. The Release boxes of a delivery are parseChecklist(maskComments(text), { section: "Release" }) — one line — and that is the reader both delivery tick and delivery check use (change 0228).
  3. When two surfaces report on the same boxes, make them call the SAME function. Two readers drift: in 0.20.0 delivery check counted - [ ] with its own regex while tick used the model, so a + [ ] claim was tickable and invisible to the check.
  4. A write keeps the file's line ending: edit in LF if you must, then withEol(text, eolOf(original)) from lib/fs-ops.js.
  5. If the model genuinely lacks the shape you need, add it to doc-model.js with its test — never a private copy in the caller.
  6. Run node --test test/one-box-count.test.js before the full suite: it greps src/ for a box-state capture outside the model.

Anti-patterns

  • const m = line.match(/^\s*[-*]\s*\[([ xX])\]\s*(.*)$/) in a command module. It looks harmless and is the sixth copy of a grammar that had six owners and three different answers for the same file (ADR 0021).
  • Splitting on \n after reading an artifact: a Windows checkout is CRLF, and the last field of every line carries a \r.
  • Skipping comments by deleting them before parsing: offsets move, and an op value that legitimately contains <!-- --> is corrupted.

Related material

  • ADR 0021 — one document model owns the .doctrina on-disk grammar.
  • packages/doctrina-cli/src/lib/doc-model.js — the owner.
  • packages/doctrina-cli/test/one-box-count.test.js — the guard.
  • The check-the-line-ending-before-patching skill — the same discipline for edits made by hand or by script.

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.