Feedback

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

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 (per ADR 0054).

Step 2: Investigate

The depth of investigation depends on the feedback type.

Full investigation (correction, complaint, observation): Trace the root cause.

1. Find the code path. Grep for relevant functions, handlers, prompts, or config in infra/scheduler/src/, .claude/skills/, decisions/, and CLAUDE.md. Read the actual code — do not guess.
2. Find the history. Check git log for recent changes to the relevant files. Check project README logs and experiment records for context.
3. Find prior feedback. Grep interaction logs (~/.scheduler/metrics/interactions.jsonl), diagnosis files (projects/<project>/diagnosis/diagnosis-*.md), and postmortems (projects/<project>/postmortem/postmortem-*.md) for similar issues.
4. Attribute to CI layer:
   • L0 Code: bug or missing feature in infrastructure
   • L1 Model: LLM capability limitation
   • L2 Workflow: process or procedure gap
   • L3 Interface: prompt, message format, or UX issue
   • L4 Evaluation: metrics or validation gap
   • L5 Human: governance, approval, or communication gap
5. State the root cause in one sentence: "The system does X because Y, but the human expects Z because W."

Light investigation (directive, approval, resource, strategy, knowledge, calibration, tuning, schedule): Verify feasibility and find the right files to change.

1. Read the relevant files to understand current state.
2. Check 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:

Scope check: If the fix requires >5 files or an architectural change, use EnterPlanMode first.

Quantitative feedback requirement: If the feedback was classified as quantitative (contains number + comparison operator), the fix MUST include a verification mechanism per ADR 0054:

1. Measurement — Code that computes the metric (e.g., utilization formula in fleet-status.ts)
2. Alert — Mechanism that fires when the metric is outside the target range (e.g., warning in health-watchdog.ts)
3. Baseline — Record the metric value at the time of change (in the feedback record)

If you cannot implement verification (e.g., no code path to measure), document why and add a task to create the measurement infrastructure.

Step 4: Implement

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

Code changes (infra/scheduler)

1. Write tests first (TDD) — no production code without a failing test first (per /develop skill's Iron Law)
2. Implement the change
3. Verify: cd infra/scheduler && npm test and npx tsc --noEmit
4. Deploy: git commit && git push && npm run build && curl -s -X POST http://localhost:8420/api/restart (graceful drain — ADR 0018)

Skill/prompt changes

1. Edit the relevant SKILL.md or prompt-building code
2. If touching TypeScript: test + type-check + deploy
3. If touching only markdown: commit

Convention/decision changes

1. Write the decision record to decisions/NNNN-title.md
2. Propagate to all locations that reference the convention (CLAUDE.md, SOPs, skills)
3. If the ADR includes Migration or Consequences with action items not implemented in this session, create corresponding tasks in the relevant project's TASKS.md (ADR task bridge — see CLAUDE.md Decisions section)
4. Commit

Project roadmap changes (reprioritization, new tasks, dropped tasks)

1. Read the project's TASKS.md.
2. Apply the feedback: add tasks, remove tasks, reorder priorities, add/change lifecycle tags.
3. If the feedback conflicts with Mission or Done when — those are fixed at project creation and cannot be changed. Write the conflict to APPROVAL_QUEUE.md instead.
4. Compositional consistency check: After modifying tasks, verify: (a) no task combines blocked and unblocked work — if an upstream task was split, check whether downstream tasks should also be split; (b) [blocked-by] tags reference only conditions requiring external action, not implementation steps the agent can perform.
5. Add a log entry to the project README explaining what changed and why (referencing the feedback).
6. Commit.

Approval resolution

The PI is the authority who resolves APPROVAL_QUEUE.md items. When they give approval feedback:

1. Read APPROVAL_QUEUE.md and find the matching pending item.
2. Move it from ## Pending to ## Resolved with the PI's decision (approved/denied/modified) and any notes.
3. Update the task tag: Search for matching tasks in project TASKS.md files. Change [approval-needed] to [approved: YYYY-MM-DD] using the approval date. This prevents tasks from being skipped by orient due to stale tags.
4. If approved, execute the approved action (e.g., edit budget.yaml, launch experiment).
5. Add a log entry to the relevant project README.
6. Commit.

Resource changes (budget, limits)

The PI sets resource limits. When they direct a budget change:

1. Read the project's budget.yaml and ledger.yaml to understand current state.
2. Edit budget.yaml as directed (change limits, add resource types, adjust deadlines).
3. If there's a corresponding pending item in APPROVAL_QUEUE.md, resolve it.
4. Add a log entry to the project README with before/after values and rationale.
5. Commit.

Strategy shifts (project portfolio)

The PI directs research strategy. When they reshape the project portfolio:

Pause a project:

1. Set Status: paused in the project README.
2. Add a log entry explaining why.
3. If the project has scheduled jobs, disable them in .scheduler/jobs.json (set enabled: false).
4. Deploy if jobs were changed: npm run build && curl -s -X POST http://localhost:8420/api/restart (graceful drain — ADR 0018).

Resume/activate a project:

1. Set Status: active in the project README.
2. Re-enable any disabled jobs.
3. Add a log entry. Deploy if jobs changed.

Start a new project:

1. Create projects/<name>/README.md following the project README schema in CLAUDE.md (Status, Mission, Done when, Context, Log, Open questions) and projects/<name>/TASKS.md for tasks.
2. Optionally create budget.yaml if the PI specifies resource limits.
3. Add a log entry to projects/akari/README.md noting the new project.

Complete/archive a project:

1. Set Status: completed in the project README.
2. Disable scheduled jobs.
3. Add a final log entry summarizing outcomes.
4. Deploy if jobs changed.

Knowledge injection

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

1. Record the fact in the most relevant project file (README log entry, existing-data.md, datasets.md, or a new file if none fits).
2. Assess impact: does this new knowledge change priorities? Unblock tasks? Invalidate assumptions? Enable new work?
3. Create tasks in every affected project's TASKS.md. New data or capabilities relevant to a project always produce at least one task (e.g., "Evaluate new X data against existing method," "Incorporate Y into training pipeline"). If you believe no task is needed, state the justification explicitly in the feedback record's Learning section.
4. If priorities change, reorder or update lifecycle tags in affected TASKS.md files.
5. If a deadline changed, update budget.yaml deadline field if applicable.
6. Commit.

Quality calibration

The PI is raising or changing the bar:

1. Identify which artifacts the calibration applies to (experiment findings, analysis depth, documentation quality, code standards).
2. Find the relevant conventions:
   • CLAUDE.md for repo-wide standards
   • Skill SKILL.md files for skill-specific standards
   • decisions/ for established policies
3. Write or update the convention to encode the new bar. Be specific — "more rigorous" must become a concrete, checkable criterion (e.g., "all findings must include confidence intervals" or "analyses must break down by at least 3 dimensions before concluding").
4. If the change modifies governance in CLAUDE.md (approval workflow, budget rules, what requires approval), write to APPROVAL_QUEUE.md instead. Convention clarifications, gotcha additions, and skill improvements may be applied directly.
5. Propagate to all relevant locations. Commit.

Agent behavior tuning

The PI controls operational parameters:

Model changes:

1. Read infra/scheduler/src/agent.ts — AGENT_PROFILES defines model, maxTurns, maxDurationMs for each agent type (workSession, chat, autofix, deepWork).
2. Edit the profile as directed.
3. For chat model: can also be set via SLACK_CHAT_MODEL env var in infra/scheduler/.env.
4. Test + type-check + deploy.

Voice/style changes:

1. Read the "Voice & style" section in buildChatPrompt() in infra/scheduler/src/chat.ts.
2. Edit the style directives as directed.
3. Deploy.

Turn/duration limits:

1. Edit the relevant profile in AGENT_PROFILES in agent.ts.
2. Deploy.

Schedule changes

The PI controls when and how often agents run:

1. Read .scheduler/jobs.json to see current jobs (id, name, schedule, enabled).
2. Apply the change:
   • Change frequency: Edit the schedule.expr (cron) or schedule.everyMs (interval) field.
   • Enable/disable: Set enabled: true or false.
   • Add a job: Append a new job object following the Job schema in infra/scheduler/src/types.ts (id, name, schedule, payload, enabled, state).
   • Remove a job: Set enabled: false (prefer disabling over deleting for audit trail).
3. Add a log entry to projects/akari/README.md with the schedule change.
4. Deploy: curl -s -X POST http://localhost:8420/api/restart (graceful drain — ADR 0018; the scheduler re-reads jobs.json on startup).

Documentation only

1. Write the log entry, README update, or experiment record
2. Validate: pixi run validate if touching experiment records
3. Commit

Step 5: Record the learning

MANDATORY. Every feedback cycle must produce a persistent record. This is the knowledge output — it ensures the same feedback never needs to be given twice.

Create or update a file at: projects/akari/feedback/feedback-<slug>.md

Use this template:

---