majiayu000 Clarify Skill
Resolve [NEEDS CLARIFICATION: ...] markers in specification files with structured decision options.
Usage
/clarify # Clarify most recent active spec
/clarify docs/specs/001-valkey/spec.md # Clarify specific spec
Purpose
When filling out a spec, mark uncertain decisions with [NEEDS CLARIFICATION: question?]. This skill:
- Finds all clarification markers in the spec
- Presents structured options for each question
- Updates the spec with
[CLARIFIED: answer]after user decision
Workflow
1. Find Spec File
If no file specified, find the most recently modified active spec:
find docs/specs -name "spec.md" \
-not -path "*/done/*" \
-not -path "*/templates/*" \
-type f 2>/dev/null | \
xargs ls -t 2>/dev/null | head -1
2. Extract Clarification Markers
Find all [NEEDS CLARIFICATION: ...] patterns:
grep -n '\[NEEDS CLARIFICATION:' "$SPEC_FILE"
Pattern: \[NEEDS CLARIFICATION: ([^\]]+)\]
3. Present Structured Options
For each clarification marker, generate 2-3 options based on:
- Platform patterns (existing compositions, conventions)
- Security implications
- Operational considerations
- Common industry practices
Format for each question:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Q1: [Question from marker]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context: [Brief analysis of the decision]
| Option | Answer | Implications |
|--------|--------|--------------|
| A | [Suggestion 1] | [Trade-off/consideration] |
| B | [Suggestion 2] | [Trade-off/consideration] |
| C | Custom | User provides own answer |
Recommendation: [A/B] - [Brief rationale]
4. Update Spec After User Decision
Replace the marker with the clarified answer:
Before:
- [NEEDS CLARIFICATION: Should cache support cross-namespace access?]
After:
- [CLARIFIED: No, cache is namespace-scoped for security isolation per zero-trust principles]
Use the Edit tool to make this replacement.
Option Generation Guidelines
When generating options, consider:
Security Perspective
- Zero-trust networking (default deny, explicit allow)
- Least privilege (minimal permissions)
- Secrets management (External Secrets, not hardcoded)
- Network policies (CiliumNetworkPolicy)
Platform Engineering Perspective
- Consistency with existing compositions (App, SQLInstance)
- Resource naming conventions (
xplane-*prefix) - API design patterns
- KCL best practices (no mutation pattern)
SRE Perspective
- Health checks and observability
- Resource limits and scaling
- Failure modes and recovery
- Operational complexity
PM Perspective
- User experience simplicity
- Progressive disclosure (simple defaults, advanced options)
- Scope management
Example Session
Input spec has:
- [NEEDS CLARIFICATION: What should be the default eviction policy for cache?]
- [NEEDS CLARIFICATION: Should high availability be mandatory or optional?]
Skill presents:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Q1: What should be the default eviction policy for cache?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context: Eviction policy determines what happens when cache
memory is full. Common policies: LRU (Least Recently Used),
LFU (Least Frequently Used), TTL-based.
| Option | Answer | Implications |
|--------|--------|--------------|
| A | LRU (allkeys-lru) | Best for general use, predictable behavior |
| B | volatile-lru | Only evicts keys with TTL set, safer for persistent data |
| C | Custom | Specify your own policy |
Recommendation: A - LRU is the most common default, works well
for caching scenarios, and is well-understood by operators.
Your choice (A/B/C or custom answer): _
User responds: "A"
Skill updates spec:
- [CLARIFIED: LRU (allkeys-lru) - Best for general use, predictable eviction behavior]
Handling Multiple Clarifications
Process clarifications one at a time to maintain focus. After each:
- Update the spec file
- Move to next clarification
- Report progress: "Resolved 2/3 clarifications"
When All Resolved
All clarifications resolved in docs/specs/001-valkey/spec.md
Summary of decisions:
1. Eviction policy: LRU (allkeys-lru)
2. High availability: Optional, enabled via ha: true
Next steps:
- Run ./scripts/validate-spec.sh to verify spec completeness
- Complete Review Checklist (4 personas)
- Begin implementation
Related Skills
/spec- Create new specification/spec-status- View pipeline overview/create-pr- Create PR when implementation complete