AC Authoring Conventions

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• skills/review-plan/SKILL.md
• agents/epic-reviewer.md
• tests/fixtures/review-plan/README.md
• skills/audit-epic/SKILL.md
• skills/review-epic/SKILL.md

Acceptance Criteria (AC) Authoring Conventions in the Roughly project define the rigorous standards and metasyntactic notations required when defining "contracts" for stories and epics. These conventions ensure that implementation plans are verifiable, unambiguous, and structurally sound before implementation begins. By standardizing how ACs are written, the project enables automated and semi-automated validation through the review-plan subagent and the epic-reviewer agent.

These conventions primarily serve the Plan Review phase of the development pipeline, preventing "surfacing-failure traps" where vague wording leads to implementation drift or unverifiable results.
Sources: CONTRIBUTING.md:144-150, skills/review-plan/SKILL.md:1-10

Quoted Wording and Metasyntactic Markers

When ACs include example wording or expected string outputs, they must explicitly distinguish between literal requirements and structural illustrations. This is managed through specific prefix markers.

Verbatim vs. Form Markers

• verbatim: <text>: Indicates the text must match literally, byte-for-byte, at implementation. This is used when strings are load-bearing for grep verification or regex anchors.
• form: <text> (adapt for clarity): Indicates the text is illustrative of structural form. The implementer is responsible for choosing concrete wording that satisfies that structure.

If an AC contains metasyntactic notation—such as angle brackets (<placeholder>), ellipses (…), or tokens like XXX—it must carry one of these markers. If the quoted text is a plain literal string with no special notation, the marker is optional as verbatim equality is implicit.

Marker	Intent	Enforcement Logic
verbatim:	Byte-for-byte match	Required for grep patterns and fixed headings
form:	Structural illustration	Required for templates with placeholders or ellipses
(None)	Implicit verbatim	Allowed only for plain literal text

Sources: CONTRIBUTING.md:195-212, skills/review-plan/SKILL.md:48-53

Structural Invariants and Logic

AC authoring requires specific logical structures to prevent cumulative execution errors and ensure auditability.

Multi-branch Case Dispatch

When an AC or skill body partitions behavior across mutually exclusive cases (e.g., Case A vs. Case B), the dispatch instruction must explicitly state: "evaluate top-to-bottom; execute only the first matching case." This prevents "fall-through" prose where multiple cases might accidentally run on top of one another.
Sources: CONTRIBUTING.md:152-159

Sequential-structure Carve-out

Ordered steps (1, 2, 3...) do not require case-dispatch language if they are accompanied by an opening invariant clause asserting that all steps execute in order (e.g., "collect ALL decisions BEFORE any disk mutations").
Sources: CONTRIBUTING.md:164-173

Cross-epic AC Amendments

When a previously shipped AC is amended in a later epic, a specific "trail" must be maintained:

1. The amending epic becomes the canonical source for the new contract.
2. The original epic receives a back-pointer: **Amended in <new-id> — see <new-id> for the corrected contract.**.
3. The CHANGELOG.md must document the revision, referencing both the original and amending locations.
   Sources: CONTRIBUTING.md:225-235

Verification Logic and Enforcement

The review-plan subagent enforces AC conventions using a set of specific checks during implementation planning.

Key Enforcement Rules

• Mutual Satisfiability: For any pair of ACs referencing overlapping surfaces (same file, same step, same prose region), the agent verifies they are jointly satisfiable. If they create a structural impossibility, it is flagged as a blocker.
• Self-defeating Patterns: Verify commands must not search for literals that are intentionally present in new detection prose or historical docs.
• Grep Co-location Hazard: Using grep -Fc or grep -Fn is flagged if multiple edited sites might land on the same physical line, as this results in inaccurate counts.
  Sources: agents/epic-reviewer.md:29-31, skills/review-plan/SKILL.md:42-47, skills/review-plan/SKILL.md:65-68

Audit and Discovery Conventions

When a story produces audit-style output (e.g., tables or finding inventories), specific conventions apply to the artifact's location:

• Audit content must be pasted into the GitHub PR body at creation time.
• The PR body is considered the canonical discoverable artifact for reviewers.
• Plan-appendix and commit-body copies are secondary records.
  Sources: CONTRIBUTING.md:252-258

Audit Subagent Workflow

For epics with 10 or more stories, the audit process uses a batching system to maintain context efficiency.

Summary

AC Authoring Conventions in Roughly are designed to eliminate ambiguity in software specifications. By enforcing metasyntactic markers, requiring explicit dispatch logic for exclusive cases, and maintaining a strict trail for amendments, the project ensures that its gated development pipeline remains reliable. These conventions are mechanically enforced by the review-plan and epic-reviewer agents, ensuring that implementation only proceeds when the specification is structurally sound.