brand-research

# brand-research

A guided workflow for turning "go research [brand]" into a structured, reusable
**brand-context pack** — the ground-truth folder every downstream ad/video skill
reads before it generates anything. The skill is conversation-driven: the user
names a brand + product, you disambiguate, research the web, source and catalog
assets, and write a fixed set of files in a fixed shape. The shape is the whole
point — see `references/output-contract.md`.

## When to use this skill

Use when the user asks for any of:

- "Research [brand] for ads" / "set up [brand]" / "create a brand folder for [brand]."
- "Fill in the brand context" / "the brand-research docs are empty/stubs."
- Hands you a company URL (and maybe a Meta Ad Library link or some ad files) and wants context docs before any creative work.
- Any kickoff where a downstream skill needs `brand-research/*.md` + `brand-assets/manifest.json` populated.

Do NOT use when: the user wants to *make a video/ad now* (this skill only prepares
context — hand off to a production skill after), or the brand already has a
populated, current pack (run `verify_pack.py`; if it PASSes, you're done).

## What it produces

The brand-context pack at a brand root (full contract in `references/output-contract.md`):

```
<brand>/
├── brand-research/
│   ├── brand-summary.md        # what they sell / who / jobs-to-be-done / voice / never-say
│   ├── visual-identity.md      # colors / type / logo rules / photography / off-limits
│   ├── competitors.md          # ## Direct (win/lose) + ## Reference creative
│   ├── audience.md             # persona / where online / objections / proof points
│   ├── asset-urls.md           # every sourced URL + access date
│   └── ui-references.md        # ONLY if the product has notable UI
├── brand-assets/
│   ├── manifest.json           # catalog: name + usage description + kind per asset
│   ├── logos/  reference-photos/  [generated-product-shots/ generated-lifestyle/]
├── concept-brief.md            # supplementary concept seeds
└── ad-runs/                    # empty, for downstream per-ad work
```

## Pipeline overview

| Phase | What | Output | Needs key? | Gate? |
|---|---|---|---|---|
| 1 | Disambiguate the brand + product | (confirmed entity) | — | ✅ if ambiguous |
| 2 | Scaffold the brand root | folders + stub files + empty manifest | — | — |
| 3 | Web research → write the 4 docs + asset-urls.md | `brand-research/*.md` | — | ✅ user reviews |
| 4 | Existing-ad analysis (optional) | notes folded into `concept-brief.md` | — | — |
| 5 | Source logo + reference photos → register | `brand-assets/logos/`, `reference-photos/` | — | — |
| 6 | Generate brand-anchored stills (optional) | `brand-assets/generated-*/` | FAL | ✅ user approves |
| 7 | Concept brief | `concept-brief.md` | — | — |
| 8 | Verify | PASS from `verify_pack.py` | — | ✅ ship |

## Idempotency (re-runs skip what's already done)

This skill is **step-idempotent** so downstream skills (e.g. `remix-script`)
can invoke it on any brand at any time without caring whether research has
already run. Re-invocation is safe — only the missing pieces execute.

The contract:

1. **Always run `verify_pack.py` first.** If it prints `PASS`, exit
   immediately — there is nothing to do. If it `FAIL`s, parse its itemized
   error list to know exactly which phases need work.
2. **Per-phase skip rules** (each phase is gated on its own output, not on
   a global "did research run?" flag):
   - **Phase 2 — Scaffold:** `scaffold_brand.py` is already idempotent and
     won't clobber real content. Always safe to re-run.
   - **Phase 3 — Web research:** for each of the four `brand-research/*.md`
     docs, skip if the file exists, has all required headers, and contains
     no `TBD`/`TODO`/`FIXME` (the exact check `verify_pack.py` runs).
     Re-run only the docs that fail that bar. Same for
     `asset-urls.md` — skip if it already has ≥3 dated source URLs.
   - **Phase 4 — Existing-ad analysis:** skip if `concept-brief.md` exists
     and contains an `## Observed patterns from existing ads` section.
     Only run when the user provides new ad files this invocation.
   - **Phase 5 — Source assets:** skip if `brand-assets/manifest.json`
     already lists ≥1 logo asset and ≥2 reference-photos (each with a real
     `name` + usage `description`). Otherwise fetch only the missing slots.
   - **Phase 6 — Generate stills:** always opt-in and human-gated; never
     auto-run on a re-invocation triggered by a downstream skill. Skip
     unless the user explicitly asks for new imagery.
   - **Phase 7 — Concept brief:** skip if `concept-brief.md` exists,
     contains all required sections, and lists ≥6 concept ideas.
   - **Phase 8 — Verify:** always run at the end to confirm the gaps
     closed.
3. **Never overwrite real content on a skip-check pass.** If a doc exists
   but is incomplete, *amend* the missing sections rather than rewriting the
   whole file from scratch — the user's prior edits stay.
4. **Don't ask the user to confirm a skip.** A complete output is its own
   permission to move on. Only stop for the gates explicitly marked ✅ in
   the pipeline table below (and even those gates apply only to phases that
   actually ran this invocation — a skipped phase has nothing to gate).
5. **Hosts that can't run `verify_pack.py` (the goose-video local worker) get
   NO exemption from this contract.** Do the equivalent inventory by hand
   FIRST: list the brand folder (MCP `list_directory` / `read_file`), check
   every artifact against the skip rules above, and print a one-line verdict
   per artifact (`brand-summary.md: complete — skip`, `manifest.json: stub —
   patch`, `logo: missing — fetch`) BEFORE doing any research. Rewriting an
   artifact that passed its skip check is a contract violation, not diligence.
6. **`research_status: failed` describes the last RUN, not the pack.** A
   crashed run routinely leaves a complete pack missing only the finalize step
   or one asset.