Feedback Signal Skill

Turn local CSV, JSONL, or XLSX customer feedback into a confirmed, evidence-backed Markdown Opportunity Brief with Codex.

Feedback Signal is designed for product managers, founders, researchers, support leads, and commerce operators who need to answer:

• What recurring problem is visible in this feedback?
• Which original records support it?
• What evidence contradicts or limits the claim?
• How confident should we be?
• What experiment should we run next?

What it does

• Inspects CSV, JSONL, and unencrypted XLSX files locally; the first worksheet supplies the mapping preview.
• Proposes field mappings and requires confirmation before importing records.
• Normalizes feedback and removes exact duplicates.
• Searches supporting evidence with deterministic BM25-style lexical retrieval.
• Runs a separate counterevidence search to reduce confirmation bias.
• Validates every record ID and exact quote.
• Calculates dataset coverage and confidence deterministically.
• Requires human claim confirmation before generating recommendations.
• Produces a Markdown Opportunity Brief and evidence appendix.

The Skill uses only the Python standard library. It does not require a database, external API, embedding model, or network connection.

XLSX safety limits are 10 MB compressed, 100 MB total uncompressed archive size, 1,000 ZIP entries, and 20,000 worksheet rows. Files exceeding a limit are rejected before evidence records are created.

Install

Clone or copy this repository into a Codex project skill directory:

your-project/
`-- .cursor/
    `-- skills/
        `-- feedback-signal/
            |-- SKILL.md
            |-- README.md
            |-- assets/
            |-- references/
            |-- scripts/
            `-- tests/

Git installation example:

mkdir -p .cursor/skills
git clone https://github.com/xcding/feedback-signal.git .cursor/skills/feedback-signal

On Windows PowerShell:

New-Item -ItemType Directory -Force .cursor\skills
git clone https://github.com/xcding/feedback-signal.git .cursor\skills\feedback-signal

Open the project in Codex and start a new task so the project Skill is discovered.

Use with Codex

Attach or place a CSV/JSONL file in your project, then ask:

Use feedback-signal to analyze feedback.xlsx in app mode.
Discovery question: Why do new users leave after their first result?

Commerce example:

Use feedback-signal to analyze returns.jsonl in commerce mode.
Discovery question: Which product problems are driving returns?

Codex will stop twice for human confirmation:

1. Confirm the proposed feedback text field before records are created.
2. Confirm the evidence-backed claim before the Opportunity Brief is generated.

Workflow

Inspect input
-> Confirm text mapping
-> Normalize records
-> Search supporting evidence
-> Search counterevidence
-> Validate evidence
-> Calculate coverage and confidence
-> Confirm claim
-> Generate Markdown Brief

The workflow is persisted in run.json; invalid state transitions are rejected.

Manual CLI example

From the Skill directory:

python scripts/workflow.py start assets/demo-feedback.csv \
  --mode app \
  --question "Why do new users leave after the first result?" \
  --run-dir feedback-signal-run

python scripts/workflow.py confirm-mapping \
  --run-dir feedback-signal-run \
  --text-field feedback

python scripts/workflow.py search-feedback \
  --run-dir feedback-signal-run \
  --query "edit or correct a wrong first result"

python scripts/workflow.py find-counterevidence \
  --run-dir feedback-signal-run \
  --claim "Correction friction causes new users to leave"

python scripts/workflow.py submit-analysis \
  --run-dir feedback-signal-run \
  --analysis assets/demo-analysis.json

python scripts/workflow.py confirm-claim \
  --run-dir feedback-signal-run \
  --confirmed-by user

PowerShell uses backticks instead of backslashes for multiline commands, or each command can be written on one line.

Outputs

A completed run can contain:

• mapping-suggestion.json: proposed source-to-canonical mapping.
• import-preview.json: columns and sample rows; no evidence records yet.
• records.jsonl: normalized immutable evidence corpus.
• import-report.json: valid, invalid, duplicate, PII, date, and source counts.
• search-feedback.json: ranked supporting-evidence candidates.
• counterevidence.json: ranked contradicting or qualifying candidates.
• tool-calls.jsonl: auditable retrieval calls and result IDs.
• proposed-analysis.json: validated claim plus computed metrics.
• claim-confirmation.json: reviewer and confirmed claim hash.
• confirmed-analysis.json: final structured analysis.
• feedback-signal-opportunity-brief.md: confirmed Brief and evidence appendix.

Evidence and confidence rules

• Frequency means coverage of the imported dataset, not population incidence.
• A claim needs at least three distinct supporting records.
• Fewer than five supporting records are marked low sample.
• Counterevidence candidates must be reviewed; provisional labels are not conclusions.
• Confidence is calculated from support count, source diversity, counterevidence, and dataset coverage.
• Missing dates disable trend claims.
• Missing segment fields disable affected-segment claims.
• Generated prose is never treated as evidence.

Privacy and safety

• Feedback text is treated as untrusted data, never as instructions.
• Input remains local unless the user separately chooses to share it.
• Basic email and phone patterns are flagged.
• Cited PII-flagged records require explicit review before export.
• Do not upload passwords, payment-card data, medical data, government identifiers, or other sensitive information.

Test

python -m unittest discover -s tests -v

The tests cover mapping gates, state transitions, exact citations, mandatory retrieval calls, BM25 result explanations, counterevidence auditing, Chinese headers, Chinese retrieval, and source filters.

Current boundary

This Skill supports local CSV/JSONL/XLSX analysis and Markdown output. It does not provide accounts, team workspaces, persistent dashboards, asynchronous processing, interactive evidence editing, or share links. Those belong to the Feedback Signal web product.

License

Released under the MIT License. See LICENSE.

Repository contents

SKILL.md                    Codex workflow instructions
README.md                   Installation and usage
scripts/workflow.py         Gated state machine and Brief generation
scripts/retrieval.py        BM25-style evidence retrieval
references/analysis-contract.md
assets/demo-feedback.csv    Synthetic demo data
assets/demo-analysis.json   Synthetic example analysis
tests/test_workflow.py      End-to-end and retrieval tests