Archetype Talk — working rules

These rules are the source of truth for every agent (Claude, Codex, Gemini, …), not just Claude Code. AGENTS.md is the cross-tool entry point and GEMINI.md a thin pointer; both defer here for the full ruleset.

UX-research knowledge graph you can talk to. Shape: Evidence → Signal → (Persona ↔ Archetype) → Idea, with Hypothesis as the ungrounded waiting room before Idea. One entity per file, one folder per type (Evidence/, Signals/, Archetypes/, Personas/, Hypotheses/, Ideas/, opt-in Competitors/; raw input in Transcripts/ and Inbox/). Each folder has a _template.md.

Which project am I in? project_name: in Product Context.md — that file is the brief for the work in this repo, and reading it is the first thing to do before answering anything about what the user is working on. Everything in the entity folders is either that project's or carries demo: true; the two live side by side and only that flag tells them apart (hard rule 9).

Hard rules (never break)

1. A persona conversation never creates data. /persona-talk output = research questions for Research backlog.md and, with the user's in-conversation approval, Hypotheses/ entries (always L1 assumptions, never presented as findings) — never Signals/ or Evidence/. A Signal exists only after a real interview/test (/extract-findings).
2. Signal = our own interview/test observation; Evidence = desk research / external or internal data. Web finds, analytics numbers, and imported insights are always Evidence — filing them as Signals inflates grounding.
3. Never invent quotes, statistics, dates, or sources. Verbatim quotes stay in their original language — they are data.
4. Contradictions are data, not noise — two conflicting Signals stay as two files; flag, don't average or overwrite.
5. Levels, not vibes: every claim carries a Level (L1 assumption → L2 evidence-only → L3 signal-only → L4 validated → L5 +correlation) — canonical definition in .claude/skills/ai-persona/references/levels.md. The same 1–5 ladder describes persona maturity. Data older than 3 months gets flagged for a refresh round.
6. Linking is the researcher's material. Relative links, URL-encoded (spaces %20, apostrophes %27). You may propose link/graph rewiring (e.g. from /graph-lint), but changes to how entities link get applied only after the user approves them — batch trivial mechanical fixes into one approval, list meaning-changing ones individually. Never silently rewire hand-written links.
7. A number is only as good as the document it came from. Verify headline figures in the primary source — the report itself, not press coverage of it, and not another agent's summary. Press repeats of one report routinely disagree with it and with each other; when they do, the report wins and the disagreement is worth a line in the file. A figure spoken from memory in an interview or podcast is not Evidence: it stays in the Signal or Transcript, flagged as a spoken estimate, and only a publication promotes it. When two credible sources attribute the same finding to different owners, record the conflict and cite it as unresolved — never quietly pick the more convenient attribution.
8. Extract blind to the thesis. When mining any source, you are recording what is in it, not looking for support. Grep to navigate, never to select — searching a transcript for the vocabulary of your current argument returns your own argument. Read the whole source, extract per subject it raises, actively keep what cuts against the current claim, and note the speaker's self-contradictions instead of taking the convenient half. Never write "this confirms our thesis": agreement between a commentator and an analysis is not evidence, usually both read the same public data. Every claim gets an honest line about what it does not settle — if you cannot write that line, you have not understood the source.
9. The demo is not the project. The bundled example set lives in the same folders as the user's research and is marked demo: true — nothing else separates them. Treat every demo: true file as out of scope: not read, not grepped, not counted, not named in an answer, unless the user asks about the demo itself. A demo persona offered next to the user's own is the failure this rule exists to prevent, and "the repo looks empty" almost always means the real files were filtered out by accident. .claude/cache/graph-index.md lists both sets separately and names the active project; the SessionStart hook says the same thing at the top of every session.

Data lifecycle (optional fields — never a blocker)

Transcripts may carry lifecycle frontmatter (consent, consent_scope, retention_until, anonymization, key_location, special_category — schema in Transcripts/_template.md). Absence means "not recorded", never "not allowed": nothing is blocked, no analysis is refused, no answer is withheld. Say something once, then get on with the work.

• consent_scope gates the matching action, when present. No ai_processing → say so before deep analysis and offer the local pre-scrub route; no verbatim_quotes → paraphrase instead of quoting; no voice_synthesis → don't offer [speak]; no external_sharing → flag it in /export. When the field is absent, proceed normally.
• special_category (GDPR Art. 9) travels with the data. Inherit it from transcript to Signal when the quote itself carries it. It never weakens a finding and never gets dropped — Tom's dyslexia is the sharpest thing in that persona. It only means: not into a voice call or an export by default, and named explicitly when /forget-participant or /retention touches it.
• Retention is a state change, not a delete. Past retention_until, the first proposal is always de-identification (finish the scrub, then key_location: destroyed) — which stops the clock, because anonymous data is out of scope of the GDPR. Deletion only when the text itself still identifies. Never delete a file on your own; the researcher decides. Freshness (3 months, is the finding still true?) and retention (may we still hold this?) are separate clocks — don't conflate them.
• Erasure re-grades the graph. Removing a source can drop a claim's Level (L4 → L3, or ungrounded). Recompute and report the drop plainly; a persona standing on deleted evidence is worse than either outcome.
• data_residency: EU in .claude/preferences.local.md (when present): before calling any service outside the EU — ElevenLabs [speak], the favicon fetch, an external image, a connector known to be non-EU — ask first and name the service. It's a reminder, not a block: the model provider is configured in the user's agent, not here. Absent field = no constraint.

Conventions

• The repo ships in English; adapt to the user's language at runtime. This includes the output templates inside every skill — headings, table columns, section names, fixed phrases like Sources: are shapes to fill in the conversation's language, never strings to transcribe. They are English because the repo is, not because your answer must be. What keeps its original form: verbatim participant quotes (translating them falsifies the record — a translation may only follow on its own bracketed line under the original, see /catalog), frontmatter field names and values, file and folder names, [S#]/[E#] markers, and dates. Frontmatter written into files stays English-keyed whatever language the chat is in.
• Demo content carries demo: true in frontmatter — illustrative, not real research. Workspaces: demo files form a permanent, separate Demo workspace (the app shows it via the top-left switcher); everything else is the user's project workspace. When the user works on their real project, exclude demo: true files from reading/grep/triage entirely — don't spend context on demo unless the user asks about the demo itself. Never link real entities to demo ones or vice versa.
• Secrets live in .env / MCP client config, never in chat or committed files. Never read or print .env values — reference keys by name (e.g. $ELEVENLABS_API_KEY) and let the shell/tool resolve them.
• If .claude/preferences.local.md exists (written by the app's Settings page), honor it: address the user by their name:, respect context_tier_default, demo_tips and judge_enabled, and apply any "Judge instruction (override)" section in persona-talk's self-check.
• Human-curated fields are never overwritten, only questioned: affinity_lock: true on a Signal freezes its affinity:; ==fragment=={tags} highlights in Transcripts/ and Evidence/ and highlight_tags: are the team's emphasis; a Priority cell in Research backlog.md ending in (locked) is the researcher's own call — you may propose priorities freely (write the bare word critical/major/minor), but a locked one you may only disagree with out loud. Treat highlighted fragments as prioritized evidence — surface them first when citing or extracting — but never add, remove or retag them yourself. Suggest the change; let the researcher make it.
• A stance is an observable, not a reading. sentiment: on a Signal records where one participant stood on one feature, using the named ladder in Signals/_template.md — never a number. Absent means not observed, never neutral; the order is for reading, never for arithmetic; two participants who disagree stay two signals and the persona shows the split. Ambiguous tone or irony → leave it out and write the question into Research backlog.md. unprompted: records who put the topic on the table (read it off the transcript's **M:**/**P:** turns): a moderator-raised stance is sound about the attitude and silent about how much it matters — asked directly, people overweight anything.
• excluded: true on a transcript means skip it in ALL analyses, triage, grep passes and extraction unless the user explicitly asks about it. It doesn't count toward sample stats or heard-from. Signals already extracted from it stay valid until the researcher reviews them — /graph-lint lists them, nothing auto-disables.
• Hypotheses are bets with zero evidence — always L1, saved only after the user approves, never counted into persona confidence or sample stats. Promotion to an Idea is the researcher's click, never automatic. Never write a full email address into an entity file. Form, author:, status: and promotion fields: Hypotheses/_template.md.
• Founder statements about users are assumptions, not findings — target group, user problem and pricing go to Hypotheses/ + Research backlog.md at L1, never to Signals/ or Evidence/. The founder is authoritative about their own product (→ Product Context.md).
• Reading the graph — cheapest route first. .claude/cache/graph-index.md (regenerated by the SessionStart hook, or python3 scripts/graph_index.py build) maps every entity: type, path, flags, links, plus each persona's slice hash, and a Topics section (tag → files) that answers "do we have anything on X?" in one read. Use it to decide which files to open — it is never a source and is never cited. For transcripts the ladder is header (abstract:/topics:) → grep → read, for evidence claim: → Key figures → read; a missing topic tag is never evidence of absence, and mentions_competitors: [] is the one field that means checked-and-none.
• The Demo workspace has its own root docs. Entity files sort themselves by demo: true, but Product Context.md and Research backlog.md have no such flag — there is one of each and it belongs to the current project. The demo's frozen copies live in docs/demo-workspace/ and scripts/embed_demo.py prefers them; edit those when you change the demo, never the root docs.
• App files are generated — never read or edit app/index.html or app/src/embedded-graph.html (300KB+ build artifacts; reading them wastes enormous context). Edit the partials instead: grep app/src/README.md first, then only the matching app/src/css/NN-*.css or app/src/js/NN-*.js (plus app/src/shell.html for structure); rebuild with python3 scripts/build_app.py, and after demo-content changes python3 scripts/embed_demo.py.
• Git: commit locally with clear messages; push only when explicitly asked.

Where the rest of the rules live

Everything above applies to every task. Workflow-specific rules live in .claude/skills/<name>/SKILL.md with the skill that has to obey them, and entity-shape rules live in each folder's _template.md — so they cost nothing until that work starts. Open the skill before doing its job. One home you would not guess: competitors — needs_research:, mentioned_in:, proximity: and the compare_categories axes are in Competitors/README.md.