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

# Export this session
claude export --format markdown > spec-kit-session-$(date +%Y%m%d).md

# Or find session ID first
claude sessions list
claude export --session <id> --format markdown > session.md

Preparing for RL Intake

If submitting to spec-kit-extensions for analysis, include:

1. Chat log (exported above)
2. Spec files created:

   cp -r specs/{{WORKFLOW}}/{{NUM}}-*/ feedback-specs/
   

3. Git commits:

   git log --oneline {{BRANCH}} > feedback-commits.txt
   

4. 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:

1. GitHub Issue: Open an issue at spec-kit-extensions repo
2. RL Intake: Maintainers run /rl-intake with your data
3. 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.