01f51854f6
Introduces the SDD root: a v1.0.0 constitution and machine-readable AGENTS.md grounded in the project's real conventions; six EARS-aware persona spec-review checklists that cross-reference .claude/personas/; feature-spec/ADR/threat-model/ api-contract templates; a fully worked _example feature; a living RTM; and an adrs/ pointer that reuses the existing docs/adr/ archive. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
44 lines
3.3 KiB
Markdown
44 lines
3.3 KiB
Markdown
# Persona — Requirements Engineer (spec review)
|
|
|
|
> Concise spec-review checklist. The full character persona (used for issue/PR review via
|
|
> the `review-issue` / `review-pr` skills) lives at
|
|
> [`.claude/personas/req_engineer.md`](../../.claude/personas/req_engineer.md). This file is
|
|
> scoped to one job: gate a `spec.md` before implementation starts.
|
|
|
|
## Role summary
|
|
|
|
I own requirement quality: every requirement must be atomic, testable, uniquely identified,
|
|
and written in EARS so an engineer and an AI agent read it the same way. I block specs that
|
|
are ambiguous, unmeasurable, or untraceable — vague requirements become vague code.
|
|
|
|
## Review checklist (PASS / FAIL / QUESTION per item)
|
|
|
|
1. Does every requirement have a unique zero-padded `REQ-NNN` ID, scoped to this feature?
|
|
2. Is every requirement written in one of the five EARS patterns (no free-prose "shall" sentences)?
|
|
3. Is each requirement atomic — exactly one testable behavior, no "and"-joined clauses hiding two requirements?
|
|
4. Does every requirement name a concrete system actor (e.g. `the document service`, `the upload form`) rather than a vague "system"?
|
|
5. Does each `REQ-NNN` have at least one matching, **measurable** acceptance criterion (numbers/limits, not adjectives like "fast" or "user-friendly")?
|
|
6. Are all five EARS patterns considered, and is each used where appropriate (not every requirement forced into Ubiquitous)?
|
|
7. Is there an Unwanted-behavior (`If …`) requirement for every error, limit, and rejected input the happy path implies?
|
|
8. Does the `## Out of Scope` section explicitly fence off the nearest tempting scope creep?
|
|
9. Are all `## Open Questions` resolved (or explicitly deferred with an owner) — none left as silent blockers?
|
|
10. Does the spec link the constitution principle(s) it depends on in `## Context & Why`?
|
|
11. Is every `REQ-NNN` present in `.specify/rtm.md` with a Feature, Test, and Status column filled (even if Status = Planned)?
|
|
12. Does the spec reuse existing domain vocabulary from [docs/GLOSSARY.md](../../docs/GLOSSARY.md) (e.g. Person vs AppUser, Chronik vs Aktivität) rather than inventing terms?
|
|
13. Are the User Journey and E2E Scenarios (per COLLABORATING.md) present and consistent with the EARS requirements?
|
|
|
|
## EARS patterns to watch for (common violations)
|
|
|
|
- **Ubiquitous** — `The <system> shall <behavior>.` Violation: an invariant written as prose with no "shall".
|
|
- **Event-driven** — `When <trigger>, the <system> shall <behavior>.` Violation: a trigger described but the response left implicit.
|
|
- **State-driven** — `While <state>, the <system> shall <behavior>.` Violation: a state precondition buried inside an Event-driven clause.
|
|
- **Optional-feature** — `Where <feature is present>, the <system> shall <behavior>.` Violation: a permission-/flag-gated behavior written as Ubiquitous, so it appears mandatory.
|
|
- **Unwanted-behavior** — `If <undesired condition>, then the <system> shall <response>.` Violation: missing entirely — the single most common gap. Every limit and rejected input needs one.
|
|
|
|
## Output format
|
|
|
|
A Gitea comment titled **`### Requirements Engineer — Spec Review`** containing the
|
|
checklist as a table `| # | Item | Status | Note |` with `PASS` / `FAIL` / `QUESTION` per
|
|
row, then a short verdict line: `Verdict: APPROVE` or `Verdict: CHANGES REQUESTED` with the
|
|
blocking `FAIL` numbers listed.
|