caro-discovery

name

caro.discovery

description

Use this skill to run a structured user-discovery interview for Caro and save the transcript into docs/discovery/transcripts/ under the project's anonymization rules. Use when a new product line or major feature spec needs to clear Gate 1 of .claude/rules/validation-discipline.md (the 20-transcripts rule). Also use to synthesize transcripts into the hypothesis ledger after each batch of 5 interviews. Triggers - "run a discovery interview for <feature>", "log this user conversation as a Caro discovery transcript", "synthesize this week's transcripts into the hypothesis ledger".

Caro Discovery Skill

This skill turns a user conversation into a properly-formatted discovery transcript that counts toward the 20-transcripts gate in .claude/rules/validation-discipline.md, and synthesizes batches of transcripts into the docs/discovery/hypothesis-ledger.md.

When this skill activates

• Run a discovery interview — guides you through the structured question script in docs/discovery/interview-template.md
• Log an organic conversation — formats an existing Discord / DM / GitHub Discussions exchange as a Caro discovery transcript (with consent)
• Synthesize a batch — after every 5 transcripts, distill the signal into the hypothesis ledger

What this skill does NOT do

• It does not invent transcripts. Every transcript must reference a real conversation with a real person. Fabricated transcripts are the fastest way to corrupt the entire validation discipline.
• It does not skip consent. Logging an existing conversation requires the participant's explicit consent (recorded as a yes/no field in the transcript front matter).
• It does not collect PII. Transcripts are anonymized at write time. See the anonymization rules in docs/discovery/README.md.
• It does not gate features by itself. This skill produces the evidence; .claude/rules/validation-discipline.md is the gate that uses the evidence.

Interview flow

1. Confirm the product line under discovery. "We're validating the hypothesis that . Today's interview is one of 20 for this hypothesis." Reference the relevant entry in docs/discovery/hypothesis-ledger.md.
2. Get consent. "May I record this conversation as an anonymized discovery transcript? It goes in a public repo under docs/discovery/transcripts/ but your handle is hashed." Record yes/no.
3. Run the interview template at docs/discovery/interview-template.md. The template enforces the "what do users do" framing (over "what would users say"), captures pain frequency / current alternatives / willingness to pay.
4. Write the transcript to docs/discovery/transcripts/YYYY-MM-DD-<hash>.md with front matter:

   ---
   date: 2026-MM-DD
   hypothesis: <hypothesis-ledger-id>
   participant_hash: <sha256-truncated-12>
   consent: yes
   channel: interview | discord | dm | github-discussion
   pain_patterns: [<pattern-tag>, ...]
   ---
   

5. Update the hypothesis ledger with the new evidence count.

Synthesis flow (after every 5 transcripts)

1. Read the 5 most-recent transcripts under the same hypothesis.
2. Identify distinct pain patterns (not 5 variations of the same one). The validation-discipline rule requires ≥3 distinct patterns from the 20-transcript set.
3. Append a synthesis entry to docs/discovery/hypothesis-ledger.md:
   • hypothesis id
   • transcript count so far
   • pattern count surfaced
   • 1-paragraph summary of the strongest signal
   • any pattern that would invalidate the hypothesis (if surfaced)
4. If a hypothesis is invalidated by the synthesis, flag it — don't silently move on. An invalidated hypothesis is signal; it saves a build cycle.

Anti-patterns this skill refuses

• Surveys-as-transcripts. A Google Form response is not a transcript. Skill will not log it.
• Filling in the blanks. If the participant didn't answer the willingness-to-pay question, that field is left empty. Don't guess.
• Skipping the hash. Participant handles are sha256-truncated. Skill will not write a transcript with a raw handle.
• Self-interviews. The interviewer cannot be the participant. Caro maintainers' opinions go in spec discussion, not in the transcript ledger.

Integration with the validation-discipline rule

A new spec that claims to clear Gate 1 (20 transcripts) must reference transcript filenames from docs/discovery/transcripts/. The reviewer can ls docs/discovery/transcripts/ | wc -l to confirm the count, and grep -l "hypothesis: <id>" docs/discovery/transcripts/ to confirm the 20 are for the right hypothesis.

This skill is one of the few sanctioned paths to producing those transcripts.