ChiefOSby ConversintStart free
Menu
← Back to the library
Library methods

Skill refinement

Track, triage, and close review feedback for collaboratively-built customer skills. Use /skill-dev-feedback whenever Patrick or Daniel wants to capture skill-testing feedback into a ledger, check what's open or blocked on a customer skill build, flip an item to Done after fixing it, or ask 'what should I work on next for Axon?' Three modes: capture (ingest feedback from a repo file, pasted blob, or Google Doc URL into a FEEDBACK.md ledger), status (record a fix with its commit hash), report (digest of open / in-progress / blocked / done items). Always use this skill for any feedback, status, or triage work on a collaborative skill build — never hand-edit FEEDBACK.md directly.

Works with the context you provideVersion 2.0.0Historical revision

# /skill-dev-feedback — collaborative skill-build feedback ledger

One skill, one system of record: a `FEEDBACK.md` ledger per customer engagement, committed to `main`. Three modes: a source-agnostic ingester, a fix recorder, and a read-only reporter.

`/skill-dev-feedback` is the item-level review ledger for customer skill builds. Do not fold it into `/project-manager`. When feedback creates project coordination work, add or update one project-level `/project-manager` task that links this ledger and summarizes the relevant open IDs. Keep individual findings, priorities, status flips, fixed-by commits, and won't-do decisions in `/skill-dev-feedback`.

Vercel preview comments are not automatically `/skill-dev-feedback`. `/website-feedback` owns raw website feedback capture and implementation workflow for managed website repos; `/vercel-feedback` is only the Vercel source adapter. Capture Vercel comments into `/skill-dev-feedback` only when they are review findings on a collaboratively-built customer skill or skill-delivery artifact; otherwise leave them in the website feedback flow and, if needed, summarize them through one `/project-manager` wrapper task.

Mode selection

Pick the mode from the first positional argument, or infer from input shape:

| First arg | Mode | Then load | |---|---|---| | `capture` | Capture new feedback from a source | `references/capture.md` | | `status` | Record a fix on one or more items | `references/status.md` | | `report` | Read-only digest of an engagement | `references/report.md` | | *(a file path, paste, or Google Doc URL)* | capture | `references/capture.md` | | *"what's open?", "what's next?", bare `/skill-dev-feedback`* | report | `references/report.md` | | *"mark AX-02 done", "AX-03 is fixed in abc123"* | status | `references/status.md` |

If the input is genuinely ambiguous between capture and status, ask. Don't silently pick between a write and a read.

Addressing feedback — the end-to-end workflow

The three modes above are operations. When you are about to *do the work* on an Open item — diagnose, fix, generate the deliverable, recursively check, and close it out — load `references/workflow.md` and follow the arc.

The workflow ties capture → root-cause diagnosis → audit-gate construction → fix → recursive check-and-fix loop → pre-flip checklist → status flip → commit + push. It encodes the seven traps from the Axon Air grant-research build (May 2026, AX-01..AX-38) so the next skill-build does not re-learn them. Specifically: the rendered-artifact rule, the keyword-vs-structured-data rule, the audit-script carveout trap, and the end-to-end smoke test as the non-negotiable shipping gate.

`workflow.md` references the mode-specific files for individual operations and the global rules (`feedback-ledger-discipline.md`, `verification-before-completion.md`) for the durable discipline.

Engagement ID

Most commands need an engagement ID (e.g. `axon-grant-research`). If none is given and only one engagement is configured, use it. If multiple are configured, list them and ask:

```bash scripts/python -c " import sys; sys.path.insert(0,'lib') import dev_feedback dev_feedback._cli(['list-engagements']) " ```

Data model

The ledger path is configured per engagement in `config/dev-feedback.json` under `ledger_path`. By convention for customer skill builds the ledger lives flat in the customer folder as `customers/<Customer>/<skill-slug> - Feedback Ledger.md` — outside the skill subdirectory so it isn't bundled when the skill is packaged. It has two zones:

  • **Status table** — scannable at a glance; regenerated automatically from detail blocks on every write. Never parse or edit the table directly; always use the CLI or `lib/dev_feedback.py`.
  • **Detail blocks** (`### AX-01 · Hi · Open`) — single source of truth. The model reads these when judging whether an incoming item is new, existing, or reworded. Each block carries `**Verbatim:**` (the feedback as given, for dedup) and an optional `**Pointers:**` (the analysis layer — file:line, lineage, fix direction — distinct from verbatim, captured only when concrete). See `references/ledger-format.md` for the full schema and `references/capture.md` §5b for when to fill pointers.

CLI essentials

All ledger mutations go through `lib/dev_feedback.py` to guarantee structural consistency and monotonic ID allocation. Never hand-edit the ledger markdown.

```bash # Add one item (called per item during capture, after user confirms) scripts/python lib/dev_feedback.py add \ --engagement axon-grant-research \ --title "Markdown → Google Docs rendering" \ --verbatim "Markdown doesn't translate properly to Google Docs (see screenshot)" \ --pointers "compose_docx.py:_markdown_to_docx → headings lost; check list-style mapping; same surface as AX-26" \ --priority Hi \ --source "Patrick test note · captured 2026-05-15" # --pointers is OPTIONAL: punchy, directive, one line (file:line · lineage · fix direction). # Omit the flag entirely when there's nothing concrete — never speculate. See capture.md §5b.

# Flip status after a fix scripts/python lib/dev_feedback.py status \ --engagement axon-grant-research \ --ids AX-02,AX-05 \ --to Done \ --commit abc1234

# Commit the ledger to main and get the GitHub URL scripts/python lib/dev_feedback.py commit \ --engagement axon-grant-research \ --message "feedback: capture review round 1 for axon-grant-research"

# Digest scripts/python lib/dev_feedback.py report \ --engagement axon-grant-research ```

Prefix arg `--by` to name who made the change (e.g. `--by Daniel`); `--note` for a free-form annotation. Both appear in the history line.

Shared output rule

**Always surface the ledger's GitHub URL** in every confirmation — the printed output of `dev_feedback commit` includes a `GitHub URL:` line; relay it to the user. This is the one-click link to inspect the current state.

Typical confirmation shape: ``` ✓ AX-02 → Done (abc1234) ✓ AX-05 → Done (abc1234) Ledger committed. GitHub URL: https://github.com/... ```

Never auto-commit on every add

Call `dev_feedback add` for each confirmed item, then call `dev_feedback commit` once at the end with a single message covering the full capture round. One commit per round, not one per item.

Next

Load the mode-specific reference — `references/capture.md`, `references/status.md`, or `references/report.md` — and follow it.