feedback

name	feedback
version	1.0.0
description	Generate structured feedback about libraries, APIs, and tools used during a coding session. Writes feedback entries that help maintainers improve documentation, fix pain points, and understand real-world usage patterns. Use after completing work that involved external libraries, APIs, or tools. Use when the agent encountered friction, errors, or documentation gaps. Use when asked to "write feedback", "report issues", or "document what worked". Optionally submits feedback to the project's feedback endpoint if configured.
allowed-tools	["Bash","Read","Write","Glob","Grep","WebFetch","AskUserQuestion"]

/feedback — Agent Feedback Flywheel

Generate structured, actionable feedback about the libraries, APIs, and tools you used during this coding session. This creates a continuous improvement loop between agents and library maintainers.

How It Works

Agent uses library → encounters friction → /feedback
    ↓
Structured feedback written to docs/agent-feedback/
    ↓
(Optional) Submitted to library's feedback endpoint
    ↓
Maintainer reviews → files issues → fixes docs → improves library
    ↓
Next agent session is smoother → writes positive feedback
    ↓
Flywheel spins faster

When to Use

• After completing a task that used external libraries or APIs
• When you hit documentation gaps, confusing APIs, or unexpected behavior
• When something worked surprisingly well (positive feedback is signal too)
• When the user asks for feedback or post-session notes
• Proactively at the end of implementation sessions

Step 1: Identify What to Give Feedback On

Scan the current session for external dependencies used:

# Check what was imported/used in recent changes
git diff HEAD~5 --name-only 2>/dev/null | head -20

Read the project's dependency files:

cat requirements.txt package.json Gemfile Cargo.toml go.mod 2>/dev/null | head -30

For each significant library/API used in this session, determine:

1. What you tried to do with it
2. What worked well (positive signal)
3. What didn't work (friction, errors, confusion)
4. Documentation gaps you encountered
5. Workarounds you had to build

Step 2: Write the Feedback Entry

Create a feedback file at docs/agent-feedback/{date}-{library}-{topic}.md:

# Feedback: {Library Name} — {Brief Topic}

**Date:** {YYYY-MM-DD}
**Library:** {name} {version}
**Agent:** {Claude/GPT/Gemini} via {Claude Code/Codex/etc.}
**Project:** {repo name}
**Session:** {what was being built}

## What I Tried To Do
{1-2 sentences describing the goal}

## What Worked Well
{Concrete examples of good API design, clear docs, smooth integration}

## Friction Points
{Each point should be specific and reproducible}

### {Issue Title}
- **What happened:** {concrete description}
- **Expected:** {what should have happened}
- **Workaround:** {what I did instead}
- **Severity:** {blocking | annoying | minor}
- **Docs gap:** {yes/no — was this a documentation issue?}

## Suggestions
{Specific, actionable improvements — not vague wishes}

## Code Examples
{If relevant, show the code that worked vs what you expected to work}

Step 3: Check for Feedback Endpoint

Look for a feedback configuration in the project:

# Check CLAUDE.md for feedback config
grep -i "feedback" CLAUDE.md .claude/settings.json 2>/dev/null

# Check if the library has a feedback endpoint
grep -ri "feedback.*endpoint\|feedback.*url\|agent.*feedback" . --include="*.md" --include="*.json" --include="*.yaml" --include="*.toml" 2>/dev/null | head -5

If a feedback endpoint is configured (in CLAUDE.md, package.json, or a .feedback.json file), offer to submit:

.feedback.json Format

Projects that want to receive agent feedback can add a .feedback.json:

{
  "endpoint": "https://api.example.com/agent-feedback",
  "method": "POST",
  "auth": "none",
  "fields": {
    "library": "required",
    "version": "required",
    "agent": "required",
    "friction_points": "required",
    "suggestions": "optional"
  }
}

If found, use AskUserQuestion:

"This project has a feedback endpoint configured. Want me to submit the feedback to {endpoint}?"

A) Submit feedback B) Save locally only

If A: POST the feedback as JSON to the endpoint. If B: Just save the file.

If no endpoint configured: save locally and note that the project can add a .feedback.json to receive agent feedback automatically.

Step 4: Update Feedback Index

If docs/agent-feedback/README.md doesn't exist, create it:

# Agent Feedback

Structured feedback from AI coding agents about libraries and tools used
in this project. Each entry captures what worked, what didn't, and specific
suggestions for improvement.

Generated by the [Feedback Flywheel](https://github.com/GhostPeony/feedback-flywheel)
skill for Claude Code.

## Entries
{auto-generated list of feedback files}

Append the new entry to the list.

Step 5: Summary

Output:

Feedback written: docs/agent-feedback/{filename}
Libraries covered: {list}
Friction points: {count}
Suggestions: {count}
Endpoint: {submitted to X / saved locally}

For Library Maintainers

Want to receive agent feedback from your users' coding sessions?

Option 1: Local Collection (No Server)

Add to your project's CLAUDE.md or AGENTS.md:

## Agent Feedback
After using this library, run `/feedback` to generate structured
feedback. Entries are saved to `docs/agent-feedback/` and included
in PRs for maintainer review.

Option 2: Hosted Endpoint

Add .feedback.json to your repo root:

{
  "endpoint": "https://yourproject.com/api/agent-feedback",
  "method": "POST"
}

Your endpoint receives:

{
  "library": "your-library",
  "version": "1.2.3",
  "agent": "claude-opus-4-6",
  "platform": "claude-code",
  "project_context": "building a web app",
  "worked_well": ["structured output", "error messages"],
  "friction_points": [
    {
      "title": "Config validation unclear",
      "description": "...",
      "severity": "annoying",
      "docs_gap": true,
      "workaround": "..."
    }
  ],
  "suggestions": ["Add config validation examples to quickstart"],
  "timestamp": "2026-03-27T12:00:00Z"
}

Option 3: GitHub Issues

Configure feedback to auto-create GitHub issues:

{
  "github_issues": true,
  "repo": "owner/repo",
  "labels": ["agent-feedback", "dx"]
}

Requires a GITHUB_TOKEN with issue creation permissions.