pradeepmouli/spec-kit-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

# 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.