agentleFS
cedricgnanscedricgnans/forge-solo/skills/forge-consistency-review/SKILL.md

forge-consistency-review

Skill0 starsChanged 3 months agoMITView on GitHub

Exit gate before any code is written. Checks cross-artifact consistency between framing, constitution, specification, design and ADRs: requirement coverage, contradictions, invented scope, ambiguities, principle violations, budget realism. Produces a report of findings graded blocking/major/minor. Use this skill before starting an implementation, whenever the user asks for a review, a validation, "is this ready", or after any change to an already-approved artifact.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are 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.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    3. Contradiction: Do two requirements contradict?

    line 30

≈ “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

Consistency review

The artifacts were written one after another, often across several sessions. Inconsistencies are born in the gaps: a requirement added after the design, a scope that grew, a decision taken in conversation and never recorded.

This review is an adversarial cold read. You are trying to make the documents fail, not to approve them. Working solo, this is the only pushback the project will ever get.

What you read

In this order: docs/00-framing.md, .forge/constitution.md, specs/<capability>/spec.md, specs/<capability>/design.md, docs/decisions/*.md. If an artifact is missing, say so and check the absence is deliberate (a bounded path has no spec — that is normal).

The eight checks

1. Coverage. Is every requirement in the spec handled by at least one component in the design? Build the requirement → component table and flag the empty rows.

2. Invention. Does every component, table, screen or endpoint in the design trace back to a requirement? An untraced element is either scope added quietly or a requirement forgotten in the spec. Both are findings.

3. Contradiction. Do two requirements contradict? Does the design contradict the spec? Does an ADR contradict another still-accepted ADR? Check numbers especially — durations, thresholds, sizes — which get miscopied between documents.

4. Ambiguity. Can a requirement be read two ways? Don't just flag it: propose the wording that settles it.

5. Constitution. Does the design violate a principle? If so, does an ADR explicitly own it? A violation without an ADR is blocking.

6. Scope. Does what is specified fit the v1 scope from the framing? Compare the framing's capability list to what is actually specified and designed. Scope drift almost always sets in between spec and design.

7. Budget. Estimate build cost in solo person-days and compare it to the time declared in the framing. If the gap exceeds a factor of two, that is a major finding — and it calls for a proposed cut, not just a warning.

8. Markers. Any [NEEDS CLARIFICATION], TBD, empty section, dead link, or ADR left in "proposed" status while the decision is already applied?

Report

Grade every finding and cite the exact location. A finding without a location is unusable.

# Consistency review — <capability> — YYYY-MM-DD

## Blocking  (resolve before any line of code)
- **[B1] <Short title>** — `spec.md §R2.4` vs `design.md §3`
  Finding: <what is wrong>
  Effect: <what breaks if left alone>
  Proposed fix: <the precise change, in which file>

## Major  (settle explicitly; may be accepted)
- **[M1] …**

## Minor  (fix as you go)
- **[m1] …**

## Checked, no finding
- Coverage: 14/14 requirements traced
- Constitution: compliant with all 6 principles

Severities

  • Blocking — the disagreement is about expected behaviour, a requirement is covered by nothing, or a principle is violated without an owned decision. Coding now would produce work to undo.
  • Major — a real risk that can be knowingly accepted: unrealistic budget, unspecified error path on an external dependency, unrecorded structural decision. You propose; the human decides and the decision is recorded.
  • Minor — wording imprecision, naming inconsistency, broken link.

Discipline of the review

  • Do not fix the artifacts yourself without approval. You find and you propose; editing silently destroys trust in approved documents.
  • Don't report what you can't locate. "The design feels fragile" is not a finding.
  • Don't invent findings to fill the page. A three-line report on a small scope is a good report. Saying "nothing to report on checks 1, 3 and 5" is information.
  • Stay in scope. Problems in existing code outside the affected path are not this review's business.

Exit

Once the blocking findings are handled, the gate is passed. Say so clearly, summarise what remains as accepted risk, and stop: the decision to begin implementation belongs to the human.

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.