1---2name: self-reported-attribution3description: >-4 Adds a free-text "How did you hear about us?" field to a B2B SaaS company's high-intent forms, codes the answers5 into channels with an editable code book, counts them by answer, opportunity and pipeline, and sets them beside6 software attribution with the gaps named, including memory bias and answers that describe navigation, not7 discovery. Use it when software attribution credits direct and branded search for most pipeline, when podcasts,8 communities, events or founder posts can't be measured, or to set up the field before a quarter starts. Not for9 UTM naming (use utm-check) or the channel report itself (use pipeline-report, which reads this).10license: MIT11compatibility: >-12 Works in Claude, ChatGPT, Codex, Cursor and any agent that reads SKILL.md. Reads a connected CRM read-only if the13 agent has one, otherwise a CSV export or pasted answers. Python 3 is optional, for coding and counting.14metadata:15 author: SHAKEUP16 version: "1.0.0"17 stage: make18 plugin: markops19 homepage: https://www.shakeuphq.com/skills/self-reported-attribution20---21 22# Self-reported attribution23 24Asks buyers where they heard about the company, turns their words into channels, and shows what software attribution can't see.25 26## Purpose27 28- One job: make the self-reported view (the field, the code book, the coded counts) and set it beside software attribution, then check it before handing it over.29- Stage: make. It ends with its own check, at most 2 rounds.30- It never adds the 2 views together or blends them into one share. They answer different questions: what made the buyer aware, and what brought the visit.31- It never changes a form or a CRM. It writes the spec; people build it.32 33## Use when / not34 35| Situation | Use |36| --- | --- |37| Software attribution credits direct traffic and branded search for most pipeline | this skill |38| Podcasts, communities, events, peers or founder posts can't be measured | this skill |39| Setting up the field before a quarter | this skill, mode `field` |40| Answers exist and need coding | this skill, mode `code` |41| UTMs land in the wrong channel | `utm-check` |42| Pipeline per channel for the board | `pipeline-report`, which reads this skill's handoff |43 44## Inputs45 46| Input | Required | Ways to provide, in order | If missing |47| --- | --- | --- | --- |48| The answers (mode `code`), with record date, software source (original source), opportunity yes or no, amount, won | yes in mode `code` | a connected CRM, read-only; a CSV export; pasted rows | switch to mode `field` |49| The forms and where leads enter (demo, contact sales, trial, content downloads) | yes in mode `field` | the reader; browse the site | ask once |50| Names worth coding: shows the company sponsors, communities, events, newsletters, partners, people who post | no | `## Channels`; the reader | code with the generic code book; open item |51| Software attribution per record | no | the same CRM export (original source); a GA4 export | the comparison is `not available`; coverage `partial` |52| The `utm-check` handoff | no | its handoff block | name software channels as the CRM writes them |53 54## Profile read55 56From `company-profile.md`: `## Company` (Brand terms, so the brand's own name isn't coded as a channel; Business model, for where to ask), `## Channels` (names of shows, communities and partners to add to the code book), `## Buyers` (who fills the forms), `## Accounts and data` (CRM), and every `## Learnings` entry for `self-reported-attribution` (accepted phrases join the code book).57 58No profile: ask for the CRM, the forms where leads enter, and the names of any podcasts, communities, events or partners the company is part of, in one message. Say that `company-profile` saves this next time.59 60## Steps61 621. **Apply learnings.** Add every accepted phrase to the code book before coding. Name each one used.63 642. **Pick the mode.**65 66 | Condition | Mode |67 | --- | --- |68 | No answers collected yet, or under 10 | `field` (steps 3 and 8 to 10) |69 | Answers exist | `code` (steps 4 to 10); add step 3 if the field breaks a rule below |70 713. **Write the field spec.**72 73 | Rule | Why |74 | --- | --- |75 | Free text, no dropdown | A list anchors answers to the options shown and hides channels nobody listed |76 | Label: "How did you hear about us?" | Plain words; the buyer answers about awareness, not about the last click |77 | Required on demo, contact sales and trial forms; leave it off content downloads | The answer matters where pipeline starts; on every download the same person answers many times |78 | Placed after the contact fields, before submit | Asked once the buyer has decided to send |79 | No prefill, no minimum length | A prefilled or forced answer is the form's words, not the buyer's |80 | Stored in a first-answer property that is never overwritten, plus a latest-answer property | The first answer belongs to the lead's creation; later forms shouldn't erase it |81 | Copied to the opportunity when it is created | Pipeline is reported per opportunity |82 | In a sales-led motion, sales asks the same question on the first call when the form had none, in its own field | Leads from outbound and events skip the form |83 84 Keep UTMs and click IDs in hidden fields beside it: that is the software view this skill compares against.85 864. **Prepare the code book.** Start from `references/code-book.csv`. Add the reader's own names (shows, communities, newsletters, events, partners, people who post) to the right code. Never add the company's own brand terms.87 885. **Code and count.** Run the script:89 90 ```91 python3 scripts/code_answers.py --csv answers.csv --extra "podcast=<show name>" --extra "linkedin_post=<founder name>"92 ```93 94 Without Python, by hand: lowercase each answer; mark blank and unsure ("don't know", "not sure") answers apart; an answer no code matches is junk when it is n/a, test, a keyboard run or has no letters, else uncoded (a short answer a code matches, such as "G2", is coded); match the code book's phrases as whole words, and when a short phrase sits inside a longer match ("linkedin" inside "linkedin ad"), keep the longer one; an answer can carry several codes, and the first one mentioned is its primary code. Count primary codes and all mentions. Say which way you ran it.95 966. **Set the views side by side.** For each code: primary answers, share of coded answers, opportunities, pipeline and won, next to what software attribution said for the same records (the top 3 software sources). Then the reading table:97 98 | Self-reported | Software | Read it as |99 | --- | --- | --- |100 | High | Low or absent | Demand made where software can't see (podcasts, peers, communities, AI assistants). Track it by its self-reported trend |101 | Low | High | The channel catches demand made elsewhere (direct, branded search, retargeting). Judge it on cost per opportunity, not on credit for creating demand |102 | High | High | Both views agree |103 | Low | Low | A candidate to cut, after 2 quarters of answers |104 105 "High" and "low" are relative to the other channels in the same run, never to an outside figure.106 1077. **Name the gaps.** Every output lists these, with the counts that show their size:108 109 | Gap | What it does | How the output handles it |110 | --- | --- | --- |111 | Memory bias | Buyers name the touch they remember, often the latest or most vivid one, not the first | Report self-reported as awareness, never as first touch |112 | Navigation answers | "Google" often means how they reached the site after hearing elsewhere | Code `search` is unclear: never credit organic or paid search from it alone |113 | Platform with no type | "LinkedIn" alone doesn't say ad or post | Code `linkedin` is unclear: credit neither |114 | Who answers | Only people who filled a form with the field answer | Report the answered share and the junk and unsure shares |115 | Small counts | One answer moves a small share a lot | Shares only from 30 coded answers; codes under 5 marked too few |116 | Software blind spots | Software can't see conversations, audio or private shares | Shown by the cross-table, not corrected |117 1188. **Check the result** (the loop below).119 1209. **Say how long until enough answers.** In mode `field`, or under 30 coded answers: from the reader's monthly demo and contact form volume, the months until 30 coded answers. Without a volume, write `not available`.121 12210. **Hand over** with the handoff block.123 124## Check and verdict125 126Checks:127 128| ID | Passes when |129| --- | --- |130| S1 | Mode `field`: the spec follows every rule in step 3. Mode `code`: the existing field breaks none of the step 3 rules that the answers or the reader show (many identical answers point to a dropdown) |131| S2 | Uncoded answers are 10% or less of text answers, after at most 2 rounds of adding phrases |132| S3 | Shares appear only with 30 or more coded answers; codes under 5 are marked too few |133| S4 | No code credits search or a platform's ads from an unclear answer |134| S5 | The 2 views are side by side and never added together |135| S6 | Every gap in step 7 is named with its count |136| S7 | Brand terms are not coded as a channel |137 138| Verdict | Condition (first match wins) |139| --- | --- |140| `BLOCKED` | No answers and no way to know where leads enter |141| `FIELD READY` | Mode `field`: the spec passes S1 |142| `NOT ENOUGH ANSWERS` | Under 30 coded answers: counts only, no shares, and the months until 30 |143| `READY WITH GAPS` | Checks pass, and software attribution or the opportunity link is missing, or S2 still fails after 2 rounds |144| `READY` | Every check passes with both views present |145 146Named stops: `BLOCKED` asks where leads enter. `NOT ENOUGH ANSWERS` stops before any share or channel ranking. No other stops.147 148## Loop149 1501. Run S1 to S7.1512. Fix: for S2, read each uncoded answer; when it names a channel, add the phrase to the code book (or the reader's `--extra`), then code again. For S3, hide the shares. For S4, move the credit to the unclear code. For S7, remove the brand phrase.1523. Check again. At most 2 rounds; list the answers still uncoded.153 154## Learn155 156- A phrase added to the code book during the loop: write a `fact` learning (`"<phrase>" codes as <code>`), so the next run starts with it.157- The reader recodes an answer: write a `proposal` with the phrase and the new code.158- After each quarter, the counts per code: write a `fact` so the trend is visible next quarter.159 160Example: `- 2026-10-24 | self-reported-attribution | fact | "the ops room" codes as community | Why: 6 answers in Q3 named it (CRM export, 2026-10) | Status: noted`161 162## Output163 164```165Verdict: <READY | READY WITH GAPS | NOT ENOUGH ANSWERS | FIELD READY | BLOCKED> · Coverage: <complete | partial (what's missing)> · Coding: <script | by hand> · Rounds: <n>166Answers: <rows> rows · <n> answered (<n%>) · <n> coded · <n> uncoded · <n> junk · <n> unsure167 168| Code | Group | Primary | Share of coded | Mentions | Opportunities | Pipeline | Won | Software said |169(by primary answers; shares only from 30 coded answers; "too few" under 5)170 171Reading: <one line per code from the reading table>172Gaps: <each gap with its count>173Still uncoded: <answers>174Field spec: <table, mode field or when the field breaks a rule>175Months until 30 coded answers: <n or not available>176Learnings applied: <list, or none>177```178 179Then the handoff block.180 181## Hand off182 183```handoff184skill: self-reported-attribution185version: 1.0.0186verdict: READY WITH GAPS187coverage: partial (no software source on 12 records)188for: <company> demo and contact forms, <period>189outputs:190 coded_answers: 84191 top_codes: {podcast: 23, word_of_mouth: 17, search: 11}192 dark_share_of_coded: 0.55193 pipeline_by_code: {podcast: 412000, word_of_mouth: 260000}194 code_book_additions: ["the ops room: community"]195next: [pipeline-report]196open: [12 records without software source]197```198 199`pipeline-report` reads `pipeline_by_code` to show the self-reported column beside software channels.200 201## Failure modes202 203| Problem | Do this |204| --- | --- |205| The field is a dropdown | Code the options as given, flag S1, and write the free-text spec |206| Answers in several languages | Code only the languages the code book covers; list the rest as uncoded with the language named |207| The reader wants one blended attribution share | Decline the blend: the views answer different questions. Show them side by side |208| A competitor's name appears in answers | Add the names as `--extra "competitor_mention=<name>"`; report that code apart, since it isn't a channel |209| The reader asks what share of answers is normal | There's no outside figure here; compare with their own last quarter |210| Answers include personal names | Code the role ("my boss" is word of mouth); don't repeat private individuals' names in the output |211 212## Influenced by213 214- Refine Labs' Hybrid Attribution Framework, which pairs what buyers say with what software records, especially for channels software misses: https://www.refinelabs.com/article/hybrid-attribution-framework215- SHAKEUP's MarkOps practice: a free-text field, an editable code book with unclear codes for navigation answers, and no blended share.