Locus Feedback

Record quality feedback on the most recent Locus run. Annotates the run's metrics file with a user verdict so retrieval quality can be tracked over time.

Usage: /locus-feedback <quality> [note]

Arguments:

• quality (required) — pass, partial, or fail (aliases: good/ok/bad)
• note (optional) — free-text explanation (quote if it contains spaces)

Examples:

/locus-feedback pass
/locus-feedback partial "Got the right room but missed the port number"
/locus-feedback fail "Answered about the wrong service entirely"

Steps

1. Resolve quality value

Map the first argument to a canonical value:

• pass or good → "pass"
• partial or ok → "partial"
• fail or bad → "fail"

If the argument is missing or unrecognized, stop and output:

Usage: /locus-feedback <pass|partial|fail> [note]

2. Find the palace root

Walk up from the current working directory looking for a directory that contains both INDEX.md and _metrics/. Stop at the filesystem root if not found.

If no palace root is found, output:

Error: no palace found (no _metrics/ directory above current path).
Run from inside a palace directory.

3. Find the most recent metrics file

List all .json files in <palace_root>/_metrics/ sorted by modification time (most recent first). Use the first result.

If _metrics/ is empty or missing:

Error: no metrics files found in <palace_root>/_metrics/.
Run a locus query first to generate a metrics file.

4. Read and validate the metrics file

Read the file. Parse as JSON. Check:

• schema_version is "1" — if not, warn but continue
• feedback field is null — if already set, output a warning:

  Warning: this run already has feedback (<existing quality>).
  Overwrite? If yes, re-run with the same command. (Proceeding to overwrite.)

Then overwrite.

5. Write feedback

Set the feedback field to:

{
  "quality": "<resolved quality>",
  "note": "<note or null>",
  "recorded_at": "<current UTC timestamp in ISO 8601>"
}

Write the updated JSON back to the same file (preserve all other fields, maintain 2-space indentation).

6. Report

Output a single confirmation line:

Locus feedback recorded: <quality> → <relative path to metrics file>

If a note was provided:

Locus feedback recorded: <quality> — "<note>" → <relative path to metrics file>

Output format

Locus feedback recorded: pass — "Got the exact IP and port" → _metrics/2026-03-02T143012Z.json

Errors use the prefix Error:, warnings use Warning:. No other output.