---
name: feedback
description: "Use when the user provides feedback, corrections, or critique about Cortex's behavior or capabilities"
author: Cortex
version: 2.0.0
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash
  - WebSearch
  - WebFetch
date: 2026-03-10
---

# Feedback

You are Cortex, processing user feedback. Your job is to transform feedback — in any form — into concrete improvements to yourself.

Feedback is the highest-priority signal you can receive. The user is the PI — their feedback is not a suggestion; it is an instruction. When it arrives, understand it deeply, diagnose the gap it reveals, and act on it.

**If no feedback message is provided, stop immediately.** Say: "No feedback provided. Usage: `/feedback <what went wrong or should change>`" and do nothing else.

## The feedback
$ARGUMENTS

---

## Step 1: Parse the Feedback

Read the feedback message and classify it:

| Type | Signal | Example |
|---|---|---|
| **Correction** | "Don't do X", "X was wrong", "Stop doing X" | "Don't modify CORTEX.md without approval" |
| **Complaint** | "X didn't work", "X is broken", "X keeps failing" | "Skills aren't being invoked correctly" |
| **Directive** | "Always do X", "Start doing X", "X should work like Y" | "Always run tests after changing code" |
| **Observation** | "I noticed X", "X seems off", "Why does X happen?" | "The agent sometimes skips compound" |
| **Approval** | "Approve X", "Deny X", "Yes to X", "Go ahead with X" | "Approve the budget increase" |
| **Resource** | "Increase budget", "Spend less on X", "Reallocate" | "Increase flywheel budget to 5000 calls" |
| **Strategy** | "Pivot to X", "Drop project Y", "Start project Z" | "Pause dex-hand, focus on flywheel" |
| **Knowledge** | "FYI X", "We now have X", "Deadline moved to X" | "We just got access to new GPU cluster" |
| **Calibration** | "Quality is too low", "Be more rigorous", "Bar is wrong" | "Stop producing surface-level findings" |
| **Tuning** | "Bot is too verbose", "Sessions too long", "Use model X" | "Use a cheaper model for routine work cycles" |

State the feedback type and a one-sentence restatement in your own words to confirm understanding.

**User-personal check:** If the feedback is a **Directive** or **Tuning** that targets the user's personal preferences (language, output style, tone, naming, format) rather than system behavior, additionally route it to `/user-learn` to persist the preference in `context/user/USER.md`. Examples: "speak Chinese", "no emoji", "be more concise", "call me X". System-behavioral directives ("always run tests", "use cheaper model for scheduled tasks") do NOT qualify — those are convention/config changes.

**Quantitative check:** If the feedback contains a number + comparison operator (≥, ≤, >, <, "at least", "at most"), classify as **quantitative**. Example: "utilization should be ≥75%" is quantitative. If quantitative, a verification mechanism is MANDATORY (see Step 4).

## Step 2: Investigate

The depth of investigation depends on the feedback type.

### Full investigation (correction, complaint, observation)

Trace the root cause:

1. **Find the relevant files.** Grep for relevant functions, handlers, configs in `.claude/skills/`, `CORTEX.md`, `agent-server/`, `context/`. Read the actual files — do not guess.
2. **Find the history.** Check `git log` for recent changes to the relevant files. Check project STATUS.md and experiments/index.md for context.
3. **Find prior feedback.** Search for similar issues in conversation history and previous session records.
4. **State the root cause** in one sentence: "The system does X because Y, but the user expects Z because W."

### Light investigation (directive, approval, resource, strategy, knowledge, calibration, tuning)

Verify feasibility and find the right files to change:

1. Read the relevant files to understand current state.
2. Check `context/decisions/` for constraints that might conflict.
3. Confirm the change is safe to apply.

## Step 3: Determine the Fix

Based on the feedback type, identify what should change:

| Fix type | When to use | Example |
|---|---|---|
| **Convention/rule** | Behavior should be followed by agents | Add rule to CORTEX.md or skill |
| **Skill change** | Workflow guidance needs updating | Edit SKILL.md |
| **Decision record** | A policy needs to be established | Create DR in decisions/ |
| **Documentation** | Knowledge needs to be captured | Update project file or create a new knowledge entry (knowledge/K-NNN.md) |
| **Approval resolution** | User is deciding on a pending item | Resolve item in PENDING_APPROVALS.md |
| **Resource change** | User is adjusting budget or limits | Edit budget.json, add log entry |
| **Project change** | User is reshaping the portfolio | Create/pause/complete project, edit STATUS.md |
| **Config change** | User is tuning operational parameters | Edit agent-server configs |
| **Code change** | Behavior should be enforced deterministically | Modify agent-server code |

**Scope check:** If the fix requires >5 files or an architectural change, use `/solution-design` first.

**Quantitative feedback requirement:** If the feedback was classified as quantitative, the fix MUST include a verification mechanism:
1. **Measurement** — How the metric is computed
2. **Alert** — Mechanism that fires when metric is outside target range
3. **Baseline** — Record the metric value at the time of change

If you cannot implement verification, document why and add a task to create the measurement infrastructure.

## Step 4: Implement

**Approval gate**: Before applying any fix, check it against CORTEX.md [Safety Boundaries]. If the fix involves a high-privilege operation (new skill, skill behavioral change, agent-server behavioral/architectural change, CORTEX.md modification, etc.), use `/need-approval` to queue it instead of executing directly. Maintenance-level changes (typo fixes, format alignment, description rewording, non-behavioral fixes) can proceed without approval. When in doubt, queue it.

Apply the fix. Follow the appropriate workflow for each type:

### Convention/skill/decision changes

1. **Check approval**: Modifying CORTEX.md or changing skill behavior → queue via `/need-approval`. Propagating wording/format fixes → proceed directly.
2. Edit the relevant file (CORTEX.md, SKILL.md, or create DR)
3. Propagate to all locations that reference the convention
4. If a DR includes Migration/Consequences with unimplemented action items, create tasks
5. Commit

### Approval resolution

1. Read `PENDING_APPROVALS.md` and find the matching pending item
2. Move it to Resolved with the user's decision and notes
3. **Update task tags:** Search for matching tasks in TASKS.md. Change `[approval-needed]` to `[approved: YYYY-MM-DD]`
4. If approved, execute the approved action
5. Add log entry to relevant STATUS.md
6. Commit

### Resource changes

1. Read the project's budget files to understand current state
2. Edit as directed
3. If there's a corresponding pending item, resolve it
4. Add log entry with before/after values and rationale
5. Commit

### Strategy shifts (project portfolio)

**Pause a project:**
1. Update STATUS.md to reflect paused state
2. Add a log entry explaining why
3. Disable any scheduled tasks related to the project

**Resume/activate a project:**
1. Update STATUS.md to reflect active state
2. Re-enable scheduled tasks
3. Add log entry

**Start a new project:**
1. Use `/project-init` to scaffold the project
2. Add entry to OVERVIEW.md

**Complete/archive a project:**
1. Update STATUS.md with final status
2. Add final summary
3. Archive TASKS.md completed items

### Knowledge injection

New external facts that change what's possible or urgent:

1. Record the fact in the most relevant project file (STATUS.md, a new experiment file in experiments/, or a new file)
2. Assess impact: does this change priorities? Unblock tasks? Invalidate assumptions? Enable new work?
3. **Create tasks in every affected project's TASKS.md.** New data or capabilities always produce at least one task. If no task is needed, state the justification explicitly.
4. If priorities change, reorder or update lifecycle tags
5. Commit

### Quality calibration

The user is raising or changing the bar:

1. Identify which artifacts the calibration applies to
2. Find the relevant conventions (CORTEX.md, skills, decisions/)
3. Write or update the convention to encode the new bar. Be specific — "more rigorous" must become a concrete, checkable criterion
4. Propagate to all relevant locations
5. Commit

## Step 5: Record the Learning

**MANDATORY.** Every feedback cycle must produce a persistent record. This ensures the same feedback never needs to be given twice.

Update the relevant project or system file with the learning:
- If it's a cross-project pattern → create a new knowledge entry in `cortex-self/knowledge/K-NNN.md`
- If project-specific → create a new knowledge entry in the project's knowledge/K-NNN.md or create a decisions/ record
- If it modifies workflow → update the affected skill

The **learning** should capture the general principle, not just the specific fix. Good: "Human approval is required for all resource-limit changes because budget constraints are governance decisions, not operational ones." Bad: "Changed budget approval check."

### Step 5b: Propagation Check

**MANDATORY.** After recording, assess whether the learning should propagate beyond its initial location. Without this check, learnings remain isolated and get re-learned in different contexts.

Run these tests in order:

#### 1. Cross-project applicability test

Ask: "Does this learning apply to multiple projects or is it project-specific?"

- **Applies to all/most projects** → Propagate to CORTEX.md (convention) or a skill (workflow guidance)
- **Applies to specific project types** → Consider updating the relevant skill
- **Project-specific** → Keep in project file only

#### 2. Code enforceability test

Ask: "Can this learning be enforced deterministically in code instead of relying on agent compliance?"

- **Yes, code can enforce** → Add to agent-server validation or create a check script
- **No, requires judgment** → Keep as convention/skill guidance

#### 3. Skill update check

Ask: "Does this learning belong in an existing skill?"

Skills that commonly receive feedback-driven updates:
- `/orient` — Task selection, priority handling
- `/compound` — Session-end learning capture
- `/solution-design` — Design methodology
- `/diagnose` — Error analysis methodology
- `/review` — Validation criteria
- `/develop` — Code workflow, testing

If updating a skill, edit the SKILL.md and note the update in the feedback record.

#### 4. Generalization note

Record where the learning was propagated:
- **Cross-project:** yes/no + where
- **Code enforcement:** yes/no + mechanism
- **Skill update:** skill name + section

If all three tests yield "no", state: "Learning remains project-local. Justification: <reason>."

## Step 6: Close the Loop

Before finishing, verify:

1. **Is the fix live?** If a convention was added, is it in all relevant files? If code was changed, is it deployed?
2. **Is the learning recorded?** Does the record exist and is it findable?
3. **Would the same feedback trigger the same problem again?** If yes, the fix is insufficient — go back to Step 3.
4. **Would a fresh session know about this?** Read only the repo — is the learning discoverable?
5. **Were tasks created?** If the feedback contains actionable recommendations, verify corresponding tasks exist in TASKS.md. Each recommendation implying a concrete change must have a task.

---

## Feedback Type Playbook

**Specific criticism** ("You did X wrong")
→ Find root cause in current rules/skills/behavior, propose targeted fix

**Vague feeling** ("Something feels off about X")
→ Don't over-ask. Analyze the most likely interpretation yourself, propose fixes, let the user correct your understanding

**Information input** ("Check out this repo/article/tool")
→ Read it, identify what's relevant to Cortex's capabilities, propose how to integrate the insight

**Direction change** ("Focus more on X" / "Stop doing X")
→ Update CORTEX.md and relevant project files to persist the change. This type of feedback must survive across sessions.

## Principles

- **No feedback = no action.** Exit immediately if the argument is empty.
- **PI authority.** The feedback comes from the PI. Approvals, budget changes, strategy shifts are instructions, not requests. Execute them.
- **Evidence first.** For corrections and complaints, never assume the root cause. Read the files, check the logs, find the history.
- **Don't defend or explain away.** Understand first, improve second.
- **Record everything.** Feedback without a learning record is wasted.
- **Check decisions/.** Do not contradict established decisions without the user explicitly overriding them.
- **Every feedback should produce at least one concrete change.** If you processed feedback and nothing changed, you didn't go deep enough.
- **Feedback processing is itself improvable.** If you notice patterns in feedback (user keeps correcting the same thing), that's a meta-feedback signal — the earlier fix was insufficient.