| name | spec |
| description | SPEC methodology workflow - bridging product requirements and technical implementation. Use when users want to create, plan, discuss, or manage feature specifications. Triggers on /spec commands or requests like "create a spec for X", "plan feature Y", "discuss requirements". |
SPEC Methodology Workflow
The SPEC methodology transforms vague feature requests into well-structured specifications through three phases: requirements, design, and tasks. This skill manages the complete spec lifecycle.
Quick Reference
Creation Commands (Choose complexity level)
| Effort | Command | Format | Use For |
|---|
| < 1 day | /spec micro <feature> | What/Why/How/Accept | Command fix, config change, simple tweak |
| 1-3 days | /spec quick <feature> | Requirements + Tasks | New slash command, button handler, event |
| 3-10 days | /spec new <feature> | All 3 phases (lean) | Multi-handler feature, new subsystem |
Collaborative Commands
| Command | Purpose |
|---|
/spec develop <feature> | Recommended: Guided brainstorm through all phases |
/spec discuss <feature> [phase] | Expert review and refinement |
/spec review <feature> | Adversarial review (PM + Engineering lenses) |
/spec requirements <feature> | Work on requirements phase |
/spec design <feature> | Work on design phase |
/spec tasks <feature> | Work on tasks phase |
/spec plan <feature> | Refine and validate task breakdown |
/spec re-plan <feature> | Mid-implementation task adjustment |
Management Commands
| Command | Purpose |
|---|
/spec status [feature] | Show spec status and progress |
/spec ready <feature> | Mark spec as ready to build |
/spec build <feature> | Start implementation from tasks |
/spec approve <feature> <phase> | Approve a specific phase |
/spec archive <feature> | Mark completed spec as done |
Decision Tree
New Work Item
|-- Effort > 1 day?
| |-- No -> /spec micro
| |-- Yes -> Multiple handlers (commands + buttons + events)?
| |-- No -> Single new command or handler?
| | |-- Yes -> /spec quick
| | |-- No -> /spec quick
| |-- Yes -> New loader/subsystem/model needed?
| |-- No -> /spec quick
| |-- Yes -> /spec new (standard)
Discord-Bot Decision Helpers
| Change Type | Complexity | Recommended |
|---|
| Fix command bug, config change | Micro | /spec micro |
| New slash command | Quick | /spec quick |
| New button handler + button ID | Quick | /spec quick |
| New event handler | Quick | /spec quick |
| Multi-handler feature (voice mgmt) | Standard | /spec new |
| New loader or subsystem | Standard | /spec new |
Codebase Quick Reference
When writing specs, reference these established patterns:
Key Utilities
- Reply:
Reply.embed(interaction, embed) / Reply.embedButtons(interaction, embed, row) — auto-adds footer
- Redis:
redis.setJson(key, value, ttl) / redis.getJson(key) — default 120s TTL
- Config: All env vars via
src/util/config/index.ts — never process.env directly
- Buttons: IDs in
src/util/config/button.ts (BUTTON_ID constant)
- Logging:
logger from src/util/log/logger.mixed.ts
- Types:
src/types/common/discord.d.ts for Client augmentation (commands, buttons Collections)
File Structure
src/commands/slash/{name}.ts # One file per slash command (auto-loaded)
src/buttons/{name}.button.ts # One file per button handler (auto-loaded)
src/events/{name}.ts # One file per event (auto-loaded)
src/models/{name}.model.ts # Mongoose schemas
src/util/config/index.ts # Typed env constants
src/util/config/button.ts # Button ID constants
src/util/decorator/reply.ts # Reply utility
src/connector/redis/index.ts # RedisService singleton
Key Constraints
- 3-second rule:
reply() or deferReply() within 3 seconds
- After deferReply: Use
editReply() only
- Types:
ChatInputCommandInteraction for commands, ButtonInteraction for buttons
- Intents: Current: Guilds, GuildMessages, GuildVoiceStates
- Embed limits: Title 256, Description 4096, Field name 256, Field value 1024, Total 6000
Constitutional Gates
Run gates at phase transitions to catch over-engineering early. See constitutional-gates.md.
Gate 1: Simplicity (Requirements)
- Can this be solved by modifying an existing command/button/event?
- Are we adding a new loader when existing patterns suffice?
- Could we delete code instead of adding it?
If any answer suggests simpler solution exists, simplify requirements first.
Gate 2: Anti-Abstraction (Design)
- Can we use existing Reply utility instead of custom response handling?
- Are we creating abstractions for a single use case?
- Could we hardcode values instead of making them configurable?
Favor extending existing patterns over creating new abstractions.
Gate 3: Integration-First (Tasks)
- Does the first task produce a working slash command or button handler?
- Can we test by running the bot and interacting?
- Are all tasks 1-4 hours with file paths?
First task should produce a testable interaction.
Phase Workflows
/spec develop <feature> — Guided Brainstorm
The recommended entry point. Guides through all phases with gates.
Step 1: Explore project context
Check existing commands, buttons, events, models, recent commits. Understand what exists.
Step 2: Ask clarifying questions
- One question per message
- Prefer multiple choice when possible
- Focus on: purpose, constraints, success criteria
- Max 5 questions per phase
Step 3: Assess scope
If the request describes multiple independent features, decompose first. Each sub-feature gets its own spec.
Step 4: Propose 2-3 approaches
Present options with trade-offs and your recommendation. Lead with the recommended option.
Step 5: Present design in sections
Scale each section to its complexity. Ask after each section if it looks right.
Step 6: Spec self-review
Check for: placeholders/TBD, internal contradictions, scope creep, ambiguous requirements. Fix inline.
Step 7: User approves
Wait for explicit approval before proceeding.
Step 8: Proceed to Requirements Phase
Apply the appropriate template based on complexity.
Key principles: One question at a time, YAGNI ruthlessly, explore alternatives, incremental validation.
Requirements Phase
Act as top-class Product Manager:
- Challenge value: "Why build this NOW vs other priorities?"
- Quantify impact: "What user behavior will change?"
- Define measurable success: "How do we know we succeeded?"
Discord-bot red flags to fix:
- Implementation details ("Add Redis cache to voice handler" -> "Voice channel state persists across bot restarts")
- Naming Discord.js internals ("Use ButtonBuilder" -> "Control panel shows management buttons")
- Referencing code patterns ("Extend VoiceStateUpdate event" -> "Bot detects when users join/leave voice")
Design Phase
Reuse-first mindset — Leverage existing patterns:
- Can we use
Reply.embed() / Reply.embedButtons() for responses?
- Does
RedisService handle the caching we need?
- Can existing button handlers be extended or composed?
- Is the auto-discovery loader pattern sufficient (no custom registration)?
Tasks Phase
Small wins — Each task should be:
- 1-4 hours max
- Clear success criteria
- End-to-end testable (run bot, interact, verify)
- Ordered by dependency
- Parallelizable tasks marked with [P]
Discord-bot task ordering pattern:
## Phase 1: Foundation (parallel-ready)
- [ ] [P] Create slash command with basic response (1-2h)
- File: src/commands/slash/{name}.ts
- [ ] [P] Add button IDs to config (0.5h)
- File: src/util/config/button.ts
## Phase 2: Core Logic (depends on Phase 1)
- [ ] Implement command logic with embeds (2-3h)
- File: src/commands/slash/{name}.ts
- [ ] Create button handlers (2-3h)
- Files: src/buttons/{name}.button.ts
## Phase 3: Events & Integration
- [ ] Create event handler (2-3h)
- File: src/events/{name}.ts
- [ ] Add Redis caching (1-2h)
Plan Refinement
/spec plan <feature> — Validate Task Breakdown
After Tasks phase, before implementation:
- Load current tasks and analyze parallelization opportunities
- Flag tasks >4 hours, suggest decomposition
- Verify first task produces demonstrable result
- Output refined plan with phase groupings and [P] markers
/spec re-plan <feature> — Mid-Implementation Adjustment
When implementation reveals plan needs changes:
- Assess: which tasks completed, which in progress, what triggered re-plan
- Identify: tasks to add [ADDED], remove [REMOVED], split, merge
- Preserve: completed tasks unchanged, in-progress context kept
- Output: updated plan with change markers
Adversarial Review
/spec review <feature> — Holistic Challenge
Structured challenge before implementation. Unlike discuss (cooperative) or self-review (structural), this asks "should we build this?"
Step 1: Load all spec content
Step 2: Spawn two subagents in parallel
PM Lens (subagent_type=Explore):
Evaluate: Problem Validity, Value Clarity, Longevity, Leverage, User Focus.
Each dimension: PASS / WARNING / CRITICAL with evidence.
Engineering Lens (subagent_type=Explore):
Evaluate: First Principles, Tech Debt, Pattern Consistency, Scale, Blast Radius.
Cross-reference codebase for pattern violations and existing solutions.
Check: src/commands/slash/, src/buttons/, src/events/, src/util/, src/connector/
Step 3: Synthesize findings
Merge, deduplicate, sort by severity: CRITICAL -> WARNING -> NOTE
Step 4: Deliver verdict
- APPROVE — Zero CRITICAL, <3 WARNING, mitigations noted
- REVISE — 1-2 addressable CRITICALs or 3+ WARNINGs
- RETHINK — 3+ CRITICALs or fundamental mismatch
See review-framework.md for detailed criteria and example output.
Build & Execution
/spec build <feature> — Task-Aware Execution
For each uncompleted task:
- ANNOUNCE: "Starting Task N: "
- PRE-CHECK: Are dependencies complete? If missing, skip to next independent task
- EXECUTE: Follow task steps sequentially
- TDD by default: write failing test -> implement -> refactor
- Each step should be 2-5 minutes of work
- No placeholders, no TODOs, no "implement later"
- VERIFY: Run
npm run build, test the interaction
- Evidence before claims — actually run the bot and verify
- UPDATE SPEC: Mark task complete in tasks.md (
- [ ] -> - [x])
- COMMIT: Atomic commit per task, reference spec in message
- BLOCKED? Stop and ask. Never guess or force through.
Execution principles:
- Bite-sized steps (2-5 min each)
- File structure first (map responsibilities before coding)
- Progress tracking in spec (crash-resilient — anyone can pick up)
- Stop on blockers (missing dep -> skip, unclear req -> ask, wrong plan -> re-plan)
Quality Limits
| Limit | Value | Rationale |
|---|
| Max questions per phase | 5 | Focus on critical unknowns |
| Max requirements | 15 | Scope creep prevention |
| Max design alternatives | 3 | Avoid analysis paralysis |
| Max tasks | 20 | Keep specs actionable |
| Task duration | 1-4 hours | Half-day completable |
If limits exceeded, split into multiple specs.
EARS Validation
Use EARS format for complex conditional requirements:
WHEN user clicks voice_lock button THE SYSTEM SHALL deny Connect for @everyone
IF user is not channel owner THEN THE SYSTEM SHALL reply with ephemeral error
For simple requirements, prefer checkboxes:
- [ ] User can create a temporary voice channel
See ears-format.md for syntax guide.
Templates
Templates for each complexity level. See templates.md.
- Micro: Single markdown file — What/Why/How/Accept
- Quick: requirements.md + tasks.md
- Standard: requirements.md + design.md + tasks.md
Spec Directory Convention
All specs live in docs/specs/ at the project root:
docs/specs/YYYYMMDD-feature-name/
Examples:
docs/specs/20260402-voice-channel-management/
docs/specs/20260403-playlist-queue/
docs/specs/20260405-fix-nsfw-filter/
Philosophy
The spec process is NOT documentation for documentation's sake.
It's a collaborative thinking tool where Claude acts as your:
- Product Partner — Challenging requirements until crystal clear
- Technical Mentor — Suggesting simpler patterns from the existing codebase
- Devil's Advocate — Finding holes before code is written
Key principle: It's easier to fix a bad idea in a spec than in code.
Examples
Creating a spec (guided)
User: /spec develop voice-channel-management
Claude: [Guides through requirements -> design -> tasks, referencing
existing voiceStateUpdate.ts, RedisService patterns, BUTTON_ID]
Quick implementation
User: /spec micro fix-voice-lock-button
Claude: [Creates minimal What/Why/How/Accept spec for button fix]
New command spec
User: /spec quick playlist-queue
Claude: [Creates requirements + tasks for new /queue command with
Redis caching and button controls]
Adversarial review
User: /spec review voice-channel-management
Claude: [Spawns PM + Engineering lens subagents, delivers APPROVE/REVISE/RETHINK verdict]
