| name | spec-kit-feedback |
| description | Capture workflow usage data for spec-kit optimization. Auto-activates when:
(1) completing a spec-kit workflow (/speckit.review, final commit),
(2) encountering friction or confusion during workflows,
(3) user mentions issues with prompts or templates,
(4) workflow deviates from expected quality gates.
Reminds to export chat logs and tracks patterns for feedback.
|
Spec-Kit Feedback Skill
Capture usage patterns during spec-kit workflows to help improve prompts and templates.
Purpose
This skill helps collect data that can be used to improve spec-kit-extensions:
- Tracks workflow completion patterns
- Identifies friction points
- Reminds to export chat logs at key moments
- Prepares data for RL intake submissions
When This Skill Activates
Workflow Completion
When a workflow reaches completion (review passed, PR created, etc.):
📋 Workflow Complete - Consider Capturing Feedback
This session used the {{WORKFLOW}} workflow. If you'd like to help
improve spec-kit, consider exporting this chat log for analysis.
Quick export:
claude export --format markdown > workflow-session.md
The spec-kit team uses this data to improve prompts and templates.
Friction Detected
When the conversation shows signs of friction:
- Multiple clarification questions
- Retries or corrections
- User redirecting the agent
- Confusion about next steps
🔍 Friction Point Noted
I noticed some confusion around [specific area]. This is valuable
feedback for improving the {{WORKFLOW}} workflow.
Consider noting this in your feedback:
- What was confusing
- What would have helped
- How it was resolved
Quality Gate Issues
When quality gates are skipped or cause problems:
⚠️ Quality Gate Observation
The {{GATE}} gate was [skipped/problematic]. This pattern helps
identify gates that may need adjustment.
If this gate felt unnecessary or blocking, note why in feedback.
Automatic Tracking
Throughout the session, this skill tracks:
Metrics (Mental Notes)
- Workflow type: Which workflow is being used
- Clarification count: How many times clarification was needed
- Retry count: How many corrections/retries occurred
- Gate compliance: Which gates were followed/skipped
- Completion status: Did workflow complete successfully
Patterns to Note
When these occur, make a mental note for the summary:
| Pattern | Indicates |
|---|
| "I don't understand" | Prompt clarity issue |
| "Let me try again" | Instruction ambiguity |
| "Actually, I meant..." | Template structure issue |
| Skipped template section | Section may be unnecessary |
| Added content not in template | Missing template section |
| User took over a step | Automation gap |
End-of-Session Summary
When the workflow completes or session ends, offer a summary:
📊 Session Summary
Workflow: {{WORKFLOW}}
Status: {{COMPLETE/PARTIAL/FAILED}}
Duration: ~{{TIME}} (estimated from conversation length)
Observations:
- Clarifications needed: {{N}}
- Retries/corrections: {{N}}
- Gates followed: {{N}}/{{TOTAL}}
{{#if friction_points}}
Friction Points:
{{#each friction_points}}
- {{this}}
{{/each}}
{{/if}}
{{#if positive_patterns}}
What Worked Well:
{{#each positive_patterns}}
- {{this}}
{{/each}}
{{/if}}
To contribute this feedback:
1. Export chat: claude export --format markdown > session.md
2. Share with spec-kit team or submit to RL intake
Export Instructions
Claude Code
claude export --format markdown > spec-kit-session-$(date +%Y%m%d).md
claude sessions list
claude export --session <id> --format markdown > session.md
Preparing for RL Intake
If submitting to spec-kit-extensions for analysis, include:
- Chat log (exported above)
- Spec files created:
cp -r specs/{{WORKFLOW}}/{{NUM}}-*/ feedback-specs/
- Git commits:
git log --oneline {{BRANCH}} > feedback-commits.txt
- Test results (if available):
npm test 2>&1 | tee feedback-tests.txt
Privacy Note
Before sharing:
- Remove proprietary business logic
- Redact API keys, passwords, personal info
- Keep workflow structure and agent interactions
- Focus on the process, not the content
Feedback Channels
Ways to share feedback:
- GitHub Issue: Open an issue at spec-kit-extensions repo
- RL Intake: Maintainers run
/rl-intake with your data
- Direct: Share exported session with maintainer
What Makes Good Feedback
Most Valuable
- Sessions with friction (confusion, retries, user takeover)
- Failed or abandoned workflows
- Workarounds you had to use
- Sections you skipped and why
- Content you added that wasn't in templates
Less Valuable
- Perfectly smooth sessions (nice, but less actionable)
- Heavily redacted sessions (hard to analyze context)
- Partial exports (missing key decision points)
Integration with Workflow Commands
This skill complements the spec-kit commands:
| Command | This Skill's Role |
|---|
/speckit.specify | Track spec creation friction |
/speckit.plan | Note planning clarifications |
/speckit.tasks | Observe task breakdown issues |
/speckit.bugfix | Monitor regression test compliance |
/speckit.review | Capture review feedback |
Suggested Workflow Tags
When exporting, consider adding tags to help categorize:
---
workflow: bugfix
friction_level: medium
gates_followed: 3/4
key_friction: "regression test timing unclear"
---
This helps the RL intake process prioritize analysis.
