specgates

CLAUDE-specgates.md

Spec-driven quality gates and conventions

Inspired by GitHub Spec Kit. These are native GIR conventions, not SpecKit dependencies.

Clarification Gate

When: Between Plan and Code phases. Before any non-trivial feature implementation begins.

Skip for: Single-file bug fixes, styling changes, copy updates, config changes.

Scan planned work against these 10 categories. Rate each Clear / Partial / Missing. Implementation MUST NOT start if any category is Missing.

#	Category	What to Verify
1	Functional scope	All user actions defined?
2	Data model	Entities, fields, relationships specified?
3	UX flow	User paths from entry to completion documented?
4	Non-functional	Performance, security, accessibility targets set?
5	Integrations	External API contracts and error handling defined?
6	Edge cases	Failure modes and boundary conditions enumerated?
7	Constraints	Budget, timeline, tech constraints stated?
8	Terminology	Ambiguous terms defined consistently?
9	Completion signals	How do we know this feature is done?
10	State transitions	For stateful features: lifecycle documented?

[NEEDS CLARIFICATION] Markers

When a requirement is ambiguous during planning, mark it inline with [NEEDS CLARIFICATION].

Rules:

• Max 3 per feature
• Priority: scope > security > UX > technical
• ALL must be resolved before coding begins
• Use AskUserQuestion to resolve — never guess

---

Acceptance Criteria Convention

Every non-trivial feature MUST include Given/When/Then acceptance scenarios. These are the definition of done.

Format (use inline in TodoWrite items or task descriptions):

## Feature: [Name]
### Acceptance
- Given [precondition]
  When [action]
  Then [expected outcome]
- Given [edge case]
  When [action]
  Then [expected outcome]

Rules:

• Minimum 2 scenarios per feature (happy path + one edge case)
• Each scenario must be independently testable
• At least one negative/error scenario for user-facing features
• Reference specific business rules from .gir/CLAUDE-activeContext.md where applicable

---

Task Format Conventions

Parallel Safety Markers

Mark parallelizable tasks with [P]. Always include target file paths.

- [ ] [P] Implement feature A — src/components/FeatureA.tsx
- [ ] [P] Add analytics metrics — src/pages/analytics.tsx
- [ ] Shared middleware update — src/middleware.ts (NOT parallel — shares file)

Tasks without [P] are sequential by default. Tasks marked [P] MUST NOT share files with other [P] tasks.

Phased Task Structure

For multi-task features, organize into 4 phases:

Phase	Name	Execution	Contents
1	Setup	Sequential	Dependencies, config, scaffolding
2	Foundational	Sequential, blocking	DB migrations, shared types, API contracts
3	User Stories	Parallelizable [P]	Feature work grouped P1→P2→P3
4	Polish	Sequential	Cross-cutting improvements, cleanup

Rule: No Phase 3 work begins until Phase 2 is complete.

Example:

## Phase 1: Setup
- [ ] Install dependencies — package.json

## Phase 2: Foundational (blocking)
- [ ] Create DB migration — migrations/
- [ ] Add shared types — types/

## Phase 3: User Stories
- [ ] [P] [US1] Feature page — src/pages/feature.tsx
- [ ] [P] [US2] Settings panel — src/pages/settings.tsx
- [ ] [US3] API handler — src/api/handler.ts

## Phase 4: Polish
- [ ] Verify security policies
- [ ] Update .gir/CLAUDE-activeContext.md

---

State Machine Convention

For any feature with >3 states, document the state machine BEFORE implementation.

Format:

[state_a] --trigger--> [state_b]
[state_b] --trigger--> [state_c]

Then add a table showing user-facing impact per state:

| State | What user sees | What's allowed | Notes |
|---|---|---|---|
| state_a | ... | ... | ... |

Projects should maintain a CLAUDE-statemachines.md file for their state machine reference.

---

spec-analyst Agent

Cross-artifact consistency auditor. Detects drift, gaps, and contradictions across GIR docs.

When: Before phase transitions, after major scope changes, when docs feel stale.

Process:

1. Read: ROADMAP.md, active TASKS.md files, .gir/CLAUDE-decisions.md, .gir/CLAUDE-activeContext.md
2. Run 6 analysis passes (cap at 30 findings):
   • Coverage: Every ROADMAP item has corresponding task entries
   • Consistency: No terminology drift between docs
   • Decision compliance: Patterns match .gir/CLAUDE-decisions.md
   • Orphans: No task items that don't trace to a roadmap item
   • Staleness: No completed items still listed as pending
   • Business rule alignment: .gir/CLAUDE-activeContext.md rules reflected in task acceptance criteria
3. Output findings table with severity (CRITICAL / HIGH / MEDIUM / LOW)
4. Suggest specific fixes with file:line references

Output format:

| # | Severity | File | Finding | Suggested Fix |
|---|---|---|---|---|
| 1 | CRITICAL | ROADMAP.md:42 | Feature X has no task entries | Create tasks |
| 2 | HIGH | .gir/CLAUDE-activeContext.md:125 | Terminology drift | Standardize |

Principles: Strict read-only. Never edit files during analysis. Cite file:line for every finding.

Invocation: "Run spec-analyst" or "Audit GIR docs for consistency"

---

Updated: 2026-02-22