spec-architect

name

spec-architect

description

Pre-code specification protocol. Use before implementing any feature, module, or service that touches business logic, data models, or external integrations. Triggers on "implement", "build", "create feature", "add endpoint", "design schema", or any request where code is the expected output but requirements are unstated. Does NOT trigger for quick fixes under 10 lines, config changes, or documentation.

Spec Architect Skill

The Rule

No code before spec. No spec before problem is understood. If you skip this skill on a non-trivial feature, you are guessing at requirements. Guesses compound into rework. The spec session costs 5 minutes. Rework costs hours.

Phase 1 — Problem Interrogation

Before proposing any solution, extract:

• What exactly changes? Name the data, state, or behaviour being modified.
• Who calls this? Identify every upstream caller or trigger (user action, cron, event, API).
• What must NOT break? List adjacent systems and contracts that must remain stable.
• What edge cases has the user NOT mentioned? Ask about: empty states, concurrent access, partial failures, rollback behavior.
• What is the acceptance criterion? Define "done" before starting.

If any answer is missing or ambiguous, ask. Do not proceed to Phase 2 with gaps. One ambiguous requirement now = one production bug later.

Phase 2 — Architecture Decision

Propose exactly ONE primary approach. State:

• Files in scope (explicit list — these will be edited)
• Files out of scope (explicit list — these will NOT be touched)
• Dependencies introduced or removed
• The single biggest risk in this approach
• One sentence on why this approach over the obvious alternatives

Do NOT list three options and ask the user to choose. Pick the best one and defend it. If the user disagrees, revise.

Phase 3 — Spec Document

Write a spec block in this exact format:

## SPEC: [Feature Name]
**Problem:** [One sentence — what is wrong or missing]
**Approach:** [One paragraph — how we are solving it and why]
**Files In Scope:** [Explicit list — will be modified]
**Files Out of Scope:** [Explicit list — will NOT be modified]
**Edge Cases Handled:** [Bullet list — each one testable]
**Acceptance Criteria:** [Checkable list — each one binary pass/fail]
**Open Questions:** [Anything requiring human decision before coding starts]

Write the spec, then STOP. Wait for explicit user approval before writing any code. Approved phrases: "looks good", "proceed", "go ahead", "approved", "ship it".

Phase 4 — Implementation

Only after approval:

1. Implement within the scope defined. Touch nothing outside Files In Scope.
2. Follow tdd-enforcer skill — tests must exist and fail before implementation.
3. If you discover a necessary change outside declared scope, STOP and surface it. Do NOT make the change. Ask first.
4. Never make "while I'm here" improvements. Scope discipline is the only rule.

Phase 5 — Session Save

After implementation:

1. Write spec summary to TASKS.md as a completed task entry.
2. If architectural decision was made, log to DECISIONS.md.
3. State: "SPEC-[name] implemented. TASKS.md and DECISIONS.md updated."

Payroll Domain Additions

For any payroll-related feature, Phase 1 must also check:

• Mid-period hire / termination handling — does this calculation apply?
• YTD accumulator crossings — does this change affect threshold behavior?
• Garnishment priority ordering and cap calculations — any impact?
• Multi-state apportionment — does this work for all active states?
• FLSA overtime thresholds — exempt/non-exempt handling correct?
• Pay period alignment — weekly, biweekly, semi-monthly, monthly all handled?
• Monetary precision — Decimal.js used throughout, no native float?

If any of these apply, add them to Edge Cases Handled in the spec.