133 lines
5.8 KiB
Markdown
133 lines
5.8 KiB
Markdown
---
|
|
allowed-tools: Bash(cat:*), Bash(ls:*), Bash(test:*), Bash(touch:*), Bash(find:*), Bash(mkdir:*), Write. Web
|
|
description: Create or review specification
|
|
argument-hint: "feature description or refinement instructions"
|
|
---
|
|
|
|
## Context
|
|
- Refinement instructions: $ARGUMENTS
|
|
- Current spec: !`cat spec/.current 2>/dev/null || echo "No active spec"`
|
|
- Project context: @CLAUDE.md
|
|
|
|
## Your Task
|
|
|
|
### Phase 0: Context Check
|
|
|
|
1. **Check for CLAUDE.md**
|
|
- If `CLAUDE.md` is not found in project root, display this warning once:
|
|
```
|
|
⚠️ No CLAUDE.md found. SPECKL works best when your project has a CLAUDE.md file with:
|
|
- Project overview and tech stack
|
|
- Explicit non-goals (what you're NOT building)
|
|
- Key constraints (performance, compliance, tech limits)
|
|
- Design values (guiding principles)
|
|
|
|
Proceeding without project context may result in less focused specifications.
|
|
```
|
|
|
|
2. **Check for README.md**
|
|
- If `spec/<current-spec>/README.md` is not found, display this warning:
|
|
```
|
|
⚠️ No README.md found in the spec directory. This file should contain the feature description
|
|
to guide spec creation. Consider running `/spkl:init "feature description"` to set up properly.
|
|
```
|
|
|
|
### Phase 1: Read Feature Description
|
|
|
|
1. **Read the README.md in the current spec directory**
|
|
- Read `spec/<current-spec>/README.md` to understand the feature description
|
|
- This is your primary source of truth for what the user wants to build
|
|
|
|
### Phase 2: Research (REQUIRED)
|
|
|
|
**Always research before proceeding:**
|
|
1. Use the README.md description to understand the feature intent and context
|
|
2. Search for similar existing implementations in the codebase
|
|
3. Research relevant best practices, technical requirements, and security/performance considerations
|
|
4. Validate assumptions about external APIs, libraries, or standards
|
|
|
|
For refinements, focus on how `$ARGUMENTS` impacts the existing spec. Present findings before Phase 3.
|
|
|
|
**Note**: The README.md acts as your research brief. Use it to guide what areas of the codebase need investigation.
|
|
|
|
### Phase 3: Spec Creation or Review
|
|
|
|
1. If `spec/<current-spec>/spec.md` **does not exist**, create it via Write with this minimal template (use README.md description and research findings to populate):
|
|
|
|
```
|
|
# <short title>
|
|
|
|
# Goal
|
|
<user/system outcome>
|
|
|
|
# Inputs
|
|
- <specific data, params, triggers - include concrete values/enums if relevant>
|
|
|
|
# Outputs
|
|
- <UI state / API / file>
|
|
|
|
# Constraints
|
|
- <stack, performance, compliance>
|
|
|
|
# Requirements
|
|
- <WHAT needs to be built, not HOW - avoid code snippets, focus on components/capabilities>
|
|
|
|
# Dependencies
|
|
- <existing systems to study before implementing - read these to understand patterns and context>
|
|
|
|
# Out of Scope
|
|
- <explicit non-goals>
|
|
|
|
# Done
|
|
- <user-observable outcomes - behaviors the user can see/test, not technical tasks>
|
|
```
|
|
|
|
2. If `spec/<current-spec>/spec.md` **exists**:
|
|
|
|
* **Print the current spec content for reference.**
|
|
* If `$ARGUMENTS` is provided, apply the refinement instructions to improve the spec.
|
|
* If `$ARGUMENTS` is empty, offer to review the spec for clarity and completeness.
|
|
* Suggest improvements as a **unified diff** (GNU diff -u format) against the existing text.
|
|
* Interpret `$ARGUMENTS` as guidance on what to clarify, tighten, or adjust (e.g., "make constraints more specific", "clarify the auth flow", "add performance requirements").
|
|
* **Do not expand scope** unless explicitly requested—focus on ambiguity removal, tighter constraints, clearer Done items.
|
|
|
|
## Critical Constraints
|
|
|
|
**Evidence-Based Suggestions Only:**
|
|
|
|
✅ **INCLUDE if there's direct evidence:**
|
|
- Systems that **already display/process this exact data type** (e.g., if transaction log shows refunds, mention it for refund reason feature)
|
|
- Areas that **must change** because they currently handle the feature being modified
|
|
- Components **explicitly named** in the user's outline or existing spec
|
|
|
|
❌ **EXCLUDE if speculative:**
|
|
- Systems that *could theoretically* use this data but don't currently (e.g., analytics that doesn't mention refunds)
|
|
- "Nice to have" integrations that aren't already connected
|
|
- Tangentially related features that *might* benefit
|
|
|
|
**Evidence test**: Before suggesting any system/area, confirm:
|
|
1. Does it **currently** handle this exact data/feature? OR
|
|
2. Did the user **explicitly mention** it in their outline?
|
|
|
|
If both answers are "no", don't include it.
|
|
|
|
## Guidelines
|
|
|
|
* KISS. Boundaries over blueprints.
|
|
* **Dependencies**: List existing systems developers should read/understand before starting. Include components you'll modify if understanding them is prerequisite.
|
|
* **Requirements**: State WHAT needs building, not HOW. No code snippets. "Create RefundReason enum", not "public enum RefundReason { ... }"
|
|
* **Done**: Observable user outcomes only. "Merchants can select refund reason" not "RefundReason enum created"
|
|
* Prefer edits that **remove ambiguity** rather than add new scope.
|
|
* Ground specs in research, not assumptions.
|
|
* If uncertain about technical details, **search first, spec second**.
|
|
* **When in doubt, leave it out.** Smaller, focused specs ship faster.
|
|
* Better to under-specify than over-promise.
|
|
* When refining, address the specific concerns in `$ARGUMENTS` while maintaining the spec's structure.
|
|
|
|
## After Completion
|
|
|
|
* For creation:
|
|
- Confirm the spec was written to `spec/<current-spec>/spec.md`
|
|
- Explain that the spec was created from the README.md description plus research findings
|
|
- Suggest running `/spkl:spec <refinements>` if changes are needed
|
|
* For refinement: Ask if user wants to apply the suggested diff |