agentleFS
GCarin1GCarin1/Doctrina/.agents/skills/write-acceptance-evidence/SKILL.md

write-acceptance-evidence

Skill1 starsChanged 11 days agoMITView on GitHub

Write acceptance criteria whose evidence actually resolves, so coverage --strict stays green and honest. Use when: The task writes or edits a spec's Acceptance criteria, or coverage reports bare/dangling criteria.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

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

    Every criterion cites its proof as a backtick path span on any of its lines (continuation lines count — the parser is …

    line 17
  2. Distinctive:

    If a criterion cannot have repo-resident proof (it describes a process adopting teams run, not this repo), do not force a fake citation — …

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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/write-acceptance-evidence.md by `doctrina index rebuild`; edit that file, not this one. -->

Skill — write-acceptance-evidence

When to use this skill

  • Authoring or editing ## Acceptance criteria in any spec.
  • doctrina coverage reports a criterion as bare, dangling, or conditional and you need to fix it honestly.

Procedure

  1. Every criterion cites its proof as a backtick path span on any of its lines (continuation lines count — the parser is packages/doctrina-cli/src/lib/criteria.js): 1. [verified] Exits 0 on success — proven by \test/cli.test.js`.`
  2. Paths resolve relative to the REPO ROOT and must exist. The classic dangling mistake: citing index.html when the file lives at docs/index.html. Write the full path from the root.
  3. A token only counts as evidence if it has a slash or a file extension and no placeholder characters — <capability>, globs, and bare words are ignored (so they neither prove nor dangle).
  4. The best evidence is executable: a test that fails if the claim stops being true. Order of preference: a test file > a checker script wired into verify.json > the implementing source file > a doc. Never cite a file merely because it exists.
  5. Mark [verified] ONLY with a citation: validate warns on a self-certified criterion ([verified] with no proof path, ADR 0008). Use [unverified] while proof is pending — an honest red beats a dishonest green.
  6. If a criterion cannot have repo-resident proof (it describes a process adopting teams run, not this repo), do not force a fake citation — rewrite the criterion to measure the deliverable that DOES live in the repo, and keep the process rubric in a separate section that coverage does not parse.
  7. Close the loop: doctrina coverage --strict must exit 0, and doctrina why <capability> must show ✓ per criterion.

Anti-patterns

  • Citing a folder or file that "should exist" without checking — the validation spec cited memory/, a folder ADR 0003 deliberately rejected, and dangled for months.
  • Citing the spec itself as its own proof (circular).
  • Flipping a criterion to [verified] in the same commit that deletes its failing test.

Related material

  • ADR 0008 — honest gates (coverage skip detection).
  • .doctrina/specs/gates/spec.md — coverage/trace semantics.
  • packages/doctrina-cli/src/lib/criteria.js — the shared parser.

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.