arogyareddy 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:
- Implement within the scope defined. Touch nothing outside Files In Scope.
- Follow tdd-enforcer skill — tests must exist and fail before implementation.
- If you discover a necessary change outside declared scope, STOP and surface it. Do NOT make the change. Ask first.
- Never make "while I'm here" improvements. Scope discipline is the only rule.
Phase 5 — Session Save
After implementation:
- Write spec summary to TASKS.md as a completed task entry.
- If architectural decision was made, log to DECISIONS.md.
- 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.