---
name: fluent-feedback
description: View, review, score, and promote skill execution feedback. Dashboard shows per-skill success/failure rates, recurring issues, effectiveness scores, authoring quality audits, and learnings ready for promotion. Triggers on "feedback dashboard", "show feedback", "review feedback", "promote learning", "skill feedback", "what went wrong", "skill effectiveness", "quality report", "skill quality", "audit skills".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: dashboard | review <skill-name> | promote <record-id> | effectiveness [<skill-name>] | quality [<skill-name>] | export [--format json|confluence]
cursor-tier: auto
---

# Skill Feedback Manager

View, analyze, score effectiveness, audit authoring quality, and promote feedback records captured during skill execution. Feedback records are written by skills after each execution (see Feedback Loop Protocol) and stored as JSONL files in `accounts/<PROFILE>/feedback/`. The `quality` command provides static analysis of SKILL.md files independent of execution data.

## Commands

### `dashboard` (default)

Show per-skill feedback summary for the current profile.

**Steps:**

1. Determine `<PROFILE>` from the active Fluent CLI profile or ask the user
2. Check if `accounts/<PROFILE>/feedback/index.json` exists
3. If yes, read it and display summary table
4. If no, scan for any `.jsonl` files in `accounts/<PROFILE>/feedback/` and rebuild index
5. If no feedback directory exists, report "No feedback captured yet" and explain how feedback gets generated

**Output format:**

```
Skill Feedback Dashboard — <PROFILE>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill                  │ Total │  OK │ FAIL │ Corrected │ Top Issue
───────────────────────┼───────┼─────┼──────┼───────────┼──────────────────
workflow-builder       │   17  │  12 │   3  │     2     │ Ghost categories
workflow-deploy        │   13  │   8 │   4  │     1     │ POST vs PUT
settings               │    8  │   5 │   2  │     1     │ Missing context
rule-scaffold          │    7  │   6 │   1  │     0     │ —

Recurring issues (3+ occurrences):
  1. UNUSED_CATEGORY_FOUND — 5 hits ← READY TO PROMOTE
  2. Wrong REST method — 3 hits ← READY TO PROMOTE
```

### `review <skill-name>`

Show all feedback records for a specific skill, grouped by outcome.

**Steps:**

1. Read `accounts/<PROFILE>/feedback/<skill-name>.jsonl`
2. Parse each line as JSON
3. Group by outcome: FAILURE and USER_CORRECTED first (most actionable)
4. For each record, show: timestamp, outcome, feature, phases summary, learnings
5. Highlight records with `confidence: "CONFIRMED"` that have 3+ occurrences — flag as "ready to promote"
6. Show user corrections prominently — these are the highest-signal feedback

**Output format per record:**

```
[2026-02-24 14:30] PARTIAL_SUCCESS — curbside-pickup (ORDER::HD)
  Phases: pre-flight ✓ → build-rulesets ✓ → deploy ✗ (UNUSED_CATEGORY_FOUND)
  Resolution: Added explicit category to all statuses
  Learning: "Never use empty string for status categories" [CONFIRMED, 5 hits]
  ← READY TO PROMOTE
```

### `promote <record-id>`

Promote a confirmed learning into a skill's Known Pitfalls section.

**Promotion guardrails (ALL must pass):**

1. Learning must have evidence from **3+ distinct sessions** (check `id` prefixes for different dates/times)
2. At least one `USER_CORRECTED` record exists for this learning, OR user explicitly says "promote this"
3. Learning text is **generic and portable** — not account-specific, not retailer-secret, not environment-only
4. If any guardrail fails: keep at `CONFIRMED`, explain why, suggest how to meet the threshold

**If guardrails pass:**

1. Read the target `SKILL.md` file for the skill referenced in the learning
2. Find or create the `## Known Pitfalls` section
3. Find or create the `<!-- feedback-promoted: managed section -->` block
4. Append the learning in format:
   ```
   - **<ERROR_CODE>** — <learning text>.
     _Source: <N> feedback records, first seen <date>, promoted <today>_
   ```
5. Write a promotion record to `.fluent-ai-skills/feedback/promotions.jsonl`:
   ```json
   {"promotedAt":"<ISO>","skill":"<name>","learning":"<text>","evidence":["<id1>","<id2>","<id3>"],"promotedBy":"user","section":"Known Pitfalls"}
   ```
6. Update the original feedback records: set `confidence` from `CONFIRMED` to `PROMOTED`

### `effectiveness [<skill-name>]`

Score skill effectiveness based on feedback data. Without a skill name, scores all skills.

**Steps:**

1. Determine `<PROFILE>` from the active Fluent CLI profile or ask the user
2. If skill name provided, read that skill's JSONL; otherwise read all `.jsonl` files in `accounts/<PROFILE>/feedback/`
3. For each skill, compute effectiveness metrics (see Effectiveness Scoring below)
4. Display scorecard

**Output format:**

```
Skill Effectiveness Report — <PROFILE>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill                  │ Score │ Grade │ Success% │ Self-Heal% │ Learn Rate │ Trend
───────────────────────┼───────┼───────┼──────────┼────────────┼────────────┼──────
workflow-builder       │  82   │  B+   │   71%    │    67%     │    0.18    │  UP
workflow-deploy        │  74   │  B    │   62%    │    50%     │    0.08    │  —
settings               │  91   │  A    │   88%    │   100%     │    0.25    │  UP
rule-scaffold          │  95   │  A+   │   86%    │   100%     │    0.00    │  —

Legend:
  Score     = weighted composite (0-100)
  Grade     = A+ (95+), A (90+), B+ (80+), B (70+), C (60+), D (50+), F (<50)
  Success%  = SUCCESS / total executions
  Self-Heal%= PARTIAL_SUCCESS resolved / (PARTIAL + FAILURE)
  Learn Rate= promoted learnings / total executions (higher = skill is still learning)
  Trend     = UP/DOWN/— based on last 10 vs previous 10 executions
```

**Effectiveness Scoring formula:**

```
score = (
    successRate * 40           // 40% weight: raw success rate
  + firstTimeSuccess * 25      // 25% weight: SUCCESS on first try (no retries/partial)
  + selfHealRate * 20          // 20% weight: recovers from failures without user help
  + (1 - correctionRate) * 15  // 15% weight: fewer user corrections = better
)
```

Where:
- `successRate` = SUCCESS count / total
- `firstTimeSuccess` = SUCCESS records where no phase has `resolution` set / total SUCCESS
- `selfHealRate` = PARTIAL_SUCCESS with resolution / (PARTIAL_SUCCESS + FAILURE)
- `correctionRate` = USER_CORRECTED / total

**Minimum data:** Require 5+ records before computing a score. Below that, show "Insufficient data (N records)".

**Trend calculation:** Compare the effectiveness score of the last 10 records vs the 10 records before that. Delta > +5 = UP, delta < -5 = DOWN, else STABLE.

**Drill-down (when single skill provided):**

After the scorecard, show:
1. **Phase failure heatmap** — which phases fail most often
2. **Top 3 recurring errors** — with occurrence counts and whether promoted
3. **User correction patterns** — what users correct most, grouped by theme
4. **Improvement suggestions** — specific, actionable recommendations based on the data:
   - If correctionRate > 20%: "High correction rate — review user corrections for pattern, consider promoting top corrections"
   - If selfHealRate < 30%: "Low self-healing — add more recovery guidance in failure scenarios"
   - If specific phase fails > 40%: "Phase '<name>' fails frequently — strengthen instructions or add guardrails"

### `quality [<skill-name>]`

Static quality analysis of skill authoring. Checks the SKILL.md file(s) against quality heuristics without requiring any execution data. Without a skill name, audits all installed skills.

**Steps:**

1. If skill name provided, locate its `SKILL.md` file; otherwise glob all `content/*/skills/*/SKILL.md`
2. For each skill, run the quality checks below and compute a score
3. Display a scorecard

**Quality checks (10 dimensions, 10 points each = 100 max):**

| # | Dimension | What to check | Points |
|---|-----------|---------------|--------|
| 1 | **Directive language** | Contains MUST, NEVER, DO NOT, always, CRITICAL | 10 |
| 2 | **Concrete examples** | At least one fenced code block or template | 10 |
| 3 | **Phase structure** | Recognizable Phase/Step/Stage headings or numbered bold steps | 10 |
| 4 | **Size bounds** | Between 500 bytes and 150KB | 10 |
| 5 | **Feedback wiring** | Has Post-Execution Feedback Capture AND Known Pitfalls with markers | 10 |
| 6 | **Pre-flight feedback** | Skills with capture also have Pre-flight Feedback Check | 10 |
| 7 | **Description quality** | Frontmatter description >= 30 chars with trigger/routing keywords | 10 |
| 8 | **Heading structure** | At least 1 H1 and 2 H2 headings | 10 |
| 9 | **Output documentation** | Documents output format, generated files, or write targets | 10 |
| 10 | **Cross-references** | References at least one other `/fluent-*` skill (handoff) | 10 |

**Scoring:**
- Each check is pass (10) or fail (0)
- Grade: A+ (95+), A (90+), B+ (80+), B (70+), C (60+), D (50+), F (<50)

**Output format:**

```
Skill Quality Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Skill                  │ Score │ Grade │ Directive │ Examples │ Phases │ Feedback │ Issues
───────────────────────┼───────┼───────┼───────────┼──────────┼────────┼──────────┼───────
workflow-builder       │ 100   │  A+   │    ✓      │    ✓     │   ✓    │    ✓     │ —
workflow-deploy        │ 100   │  A+   │    ✓      │    ✓     │   ✓    │    ✓     │ —
feature-plan           │  90   │  A    │    ✓      │    ✓     │   ✓    │    ✓     │ No output docs
settings               │ 100   │  A+   │    ✓      │    ✓     │   ✓    │    ✓     │ —

Summary: 48/52 skills score A or above. 4 skills need attention.

Top issues to fix:
  1. fluent-foo — missing feedback wiring (add Post-Execution Feedback section)
  2. fluent-bar — no code examples (add at least one fenced code block)
```

**Drill-down (when single skill provided):**

Show all 10 dimensions with pass/fail and specific remediation for failures:

```
Quality Report: fluent-workflow-builder
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Score: 100/100 (A+)

 ✓ Directive language — 14 directive keywords found (density: 8.2/1K words)
 ✓ Concrete examples — 6 code blocks found
 ✓ Phase structure — 4 phases identified
 ✓ Size bounds — 28KB (within 500B–150KB range)
 ✓ Feedback wiring — Post-Execution Capture + Known Pitfalls + markers
 ✓ Pre-flight feedback — checks feedback JSONL at start
 ✓ Description quality — 156 chars, has trigger keywords
 ✓ Heading structure — 1 H1, 12 H2
 ✓ Output documentation — documents generated workflow JSON
 ✓ Cross-references — references 5 other skills

Bonus checks:
  Ownership boundary: ✓ (has "does NOT" scope limits)
  Anti-patterns: ✓ (no TODO/FIXME in prose)
  Instruction density: 8.2/1K words (good — minimum 3.0)
```

**Combining quality + effectiveness:**

When both quality and effectiveness data exist for a skill, show a combined view:

```
Skill Health: fluent-workflow-builder
  Authoring quality:  100/100 (A+) — skill is well-written
  Execution effectiveness: 82/100 (B+) — skill performs well but has room to improve
  Recommendation: Review top user corrections for promotion candidates
```

### `export [--format json|confluence]`

Export feedback for team sharing.

**JSON format (default):** Writes all `.jsonl` files to a single `accounts/<PROFILE>/feedback/export-<date>.json` with structure:
```json
{
  "profile": "<PROFILE>",
  "exportedAt": "<ISO>",
  "skills": {
    "<skill-name>": [ ...records... ]
  }
}
```

**Confluence format:** Generates a wiki-markup table suitable for pasting into Confluence:
```
|| Skill || Issue || Occurrences || Confidence || Learning ||
| workflow-builder | UNUSED_CATEGORY_FOUND | 5 | CONFIRMED | Never use empty string for categories |
```

Write to `accounts/<PROFILE>/feedback/export-<date>.wiki` or `.json`.

## Feedback Record Schema (feedback-record-v1)

Reference schema for records written by other skills. This skill reads them; other skills write them.

```jsonc
{
  "$schema": "feedback-record-v1",
  "id": "fb-<YYYYMMDD>-<HHMMSS>-<3char>",   // unique, sortable
  "timestamp": "<ISO-8601>",
  "skill": "<skill-name>",                    // which skill produced this
  "feature": "<slug>",                        // feature slug if applicable, null otherwise
  "profile": "<PROFILE>",
  "retailer": "<retailer-name>",
  "entityType": "<ORDER|FULFILMENT|...>",     // primary entity, null if N/A
  "entitySubtype": "<HD|CC|...>",             // subtype, null if N/A

  "outcome": "<SUCCESS|PARTIAL_SUCCESS|FAILURE|BLOCKED|USER_CORRECTED>",

  "phases": [
    {
      "name": "<phase-name>",                 // e.g., "pre-flight-check", "build-rulesets", "deploy"
      "status": "<PASS|FAIL|SKIP>",
      "error": "<error-code>",               // only if FAIL
      "errorDetail": "<human-readable>",      // only if FAIL
      "resolution": "<what-fixed-it>"         // only if FAIL then resolved
    }
  ],

  "learnings": [
    {
      "type": "<GOTCHA|PATTERN|CORRECTION|WORKAROUND|CONSTRAINT>",
      "scope": "<platform|account|feature>",
      "skill": "<target-skill>",              // which skill should learn this
      "text": "<learning text>",
      "confidence": "<OBSERVED|CONFIRMED|PROMOTED>",
      "tags": ["<tag1>", "<tag2>"],
      "relatedError": "<error-code>"          // for pattern matching
    }
  ],

  "userCorrections": [
    {
      "what": "<what-agent-did-wrong>",
      "correction": "<what-user-said>",
      "impact": "<HIGH|MEDIUM|LOW>"
    }
  ],

  "tags": ["<tag1>", "<tag2>"],
  "planRef": "<path-to-plan-if-applicable>"
}
```

### Secret redaction rules

Before writing any feedback record, redact:
- `accessToken`, `clientSecret`, `password`, API keys, bearer tokens
- Any value matching patterns: `eyJ...` (JWT), `sk-...`, `token=...`

**Keep** (needed for retrieval filtering): profile name, retailer ref, entity refs, order refs, setting names, workflow names.

## Index Schema

`accounts/<PROFILE>/feedback/index.json`:

```json
{
  "$schema": "feedback-index-v2",
  "profile": "<PROFILE>",
  "lastUpdated": "<ISO-8601>",
  "skills": {
    "<skill-name>": {
      "total": 17,
      "success": 12,
      "partialSuccess": 2,
      "failure": 3,
      "blocked": 0,
      "userCorrected": 2,
      "lastUpdated": "<ISO-8601>",
      "topIssue": "UNUSED_CATEGORY_FOUND",
      "topIssueSeverity": "HIGH",
      "effectiveness": {
        "score": 82,
        "grade": "B+",
        "successRate": 0.71,
        "selfHealRate": 0.67,
        "correctionRate": 0.12,
        "trend": "UP",
        "computedAt": "<ISO-8601>"
      }
    }
  }
}
```

When rebuilding the index, always recompute effectiveness scores for skills with 5+ records.

## Rebuilding the Index

If `index.json` is missing or stale, rebuild from JSONL source files:

1. Glob `accounts/<PROFILE>/feedback/*.jsonl`
2. For each file, count records by outcome
3. For each file, find most frequent `relatedError` → `topIssue`
4. Write `index.json`

## Feedback Protocol Reference

This section is the canonical reference for how skills wire feedback. Skills MUST follow this protocol.

### Pre-flight Feedback Check (at skill start)

Every feedback-enabled skill MUST include this at the beginning of execution:

```
1. Check if `accounts/<PROFILE>/feedback/<skill-name>.jsonl` exists
2. If yes, read last 20 records
3. Filter to: same entity type/subtype if known, FAILURE or USER_CORRECTED outcomes,
   confidence = CONFIRMED or PROMOTED
4. Extract top 3 relevant learnings — use as internal "WATCH OUT" guidance during execution
5. Do NOT show raw feedback to the user — silently adjust approach based on past issues
```

### Post-Execution Feedback Capture (at skill end)

Every feedback-enabled skill MUST write a feedback record after execution:

```
1. Classify outcome: SUCCESS | PARTIAL_SUCCESS | FAILURE | BLOCKED | USER_CORRECTED
2. Build a feedback-record-v1 JSON object with:
   - skill: "<skill-name>"
   - feature: feature slug if applicable, null otherwise
   - entityType / entitySubtype: primary entity if applicable
   - phases: array tracing each phase with PASS/FAIL/SKIP
   - learnings: any gotchas discovered during execution
   - userCorrections: any corrections the user provided
3. Redact secrets: strip tokens, passwords, API keys. Keep business identifiers.
4. Append one JSON line to accounts/<PROFILE>/feedback/<skill-name>.jsonl
5. Update accounts/<PROFILE>/feedback/index.json counters (mkdir -p if missing)
```

**Skip capture if:** The execution was trivially simple (e.g., user asked a question, no actual write operation happened).

### Known Pitfalls Section (at skill end)

Every feedback-enabled skill MUST have this section at the bottom:

```markdown
## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

_(No promoted learnings yet.)_

<!-- end feedback-promoted -->
```

The `/fluent-feedback promote` command writes learnings into this managed block. Do NOT edit the content between the markers manually.

## No Planning Gate

This skill is read-only by default (dashboard, review, export, effectiveness). Only `promote` modifies files, and it has its own guardrails. No planning gate required.

## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

_(No promoted learnings yet — this section will be populated as the feedback loop matures.)_

<!-- end feedback-promoted -->
