Imported from JonathanBowker/ai-services (20-research-services/wf-digividuals-research/AGENTS.md). Install upstream with npx skills add JonathanBowker/ai-services --skill wf-digividuals-research. Copyright stays with the author.

AGENTS.md

Purpose

This file is the repo-wide operating contract for wf-digividuals-research.

Use it to keep research workflows, file structure, and agent-assisted editing consistent across contributors. It defines:

the workflow boundary of the repo
the canonical study structure
naming and file-shape rules
evidence and uncertainty rules
standard research workflows
the minimum quality bar before work is treated as done

Scope

This root file applies to the entire repository unless a more specific nested AGENTS.md overrides or extends local behavior.

Use nested AGENTS.md files only when a specific study, workflow, or script area needs tighter local rules.

The workspace root AGENTS.md still provides the master repo layout, agent hierarchy rules, logging defaults, and cross-workspace governance expectations.

Workflow role

This repository is a governed research workflow repo for designing, running, analysing, grounding, and packaging market research studies.

It should contain:

study definitions and study-specific artefacts
research methodology and SOP documents
reusable templates and schemas
prompts and research libraries
automation for initializing, validating, exporting, and rendering studies
tests that protect the workflow contract

It should not become:

a generic dumping ground for notes
a shared library repo with no research workflow boundary
a freeform prompt archive detached from study execution
a mixed domain repo unrelated to research delivery

Core principles

Keep all substantive work study-centric under studies/<study-slug>/.
Preserve the distinction between design, evidence, analysis, and outputs.
Prefer canonical structured files over ad hoc notes.
Reuse templates/ and validate against schemas/ where available.
Minimize structural drift across studies.
Be explicit about uncertainty, inference, and synthetic content.
Do not fabricate fieldwork evidence or unsupported claims.
Prefer additive edits over destructive rewrites.
Validate the repo after meaningful structural changes.

Repo layout

The canonical repo structure is:

compliance.latest.json for the root-level latest compliance mirror
.agents/skills/ for reusable Codex skills when workflow-specific reusable capabilities are added
docs/ for methodology and repository documentation
examples/ for curated repo-level examples that are smaller than full studies
config/ for shared markets, locales, and taxonomy assets
schemas/ for validation schemas
templates/ for canonical starter files
prompts/ for reusable prompt assets
libraries/ for reusable archetypes, digividuals, and signal libraries
studies/ for active study work
scripts/ for automation and validation utilities
runs/checkpoints/ for repo-level checkpoint or progress artefacts when relevant
runs/logs/ for repo-level debugging logs when scripts emit them
runs/manifests/ for repo-level compliance records
runs/outputs/ for repo-level generated workflow artifacts when they are not study-specific
tests/ for repo-level tests
archive/ for retired studies

Within each study, use:

study.yaml
design/
fieldwork/
analysis/
outputs/
logs/

Stricter alignment note:

keep the root-skeleton directories visible at repo level where practical
keep workflow-specific first-class directories such as templates/, libraries/, and studies/
do not collapse study-level runtime material into root runs/ when the study-local path is more correct

Documentation defaults and local exemptions

Apply the workspace root documentation defaults to durable repo assets.

Defaults:

add YAML front matter to durable repo-level Markdown such as README.md, AGENTS.md, docs/*.md, and prompts/*.md
keep library READMEs front-matter compliant
keep the copyright header on Advanced Analytica-owned durable docs

Local exemptions:

study-specific working Markdown under studies/*/design/ may remain front-matter free when it is intended for direct researcher editing
rendered study outputs under studies/*/outputs/ may remain front-matter free because they are presentation artifacts rendered from structured sources
study logs under studies/*/logs/ may remain front-matter free because they are generated or working run artifacts
Markdown templates under templates/study/ may omit front matter where carrying a template path into copied study files would create misleading metadata

Local environment defaults

For local development and agent-assisted work, always initialize these repo-root local environment assets by default:

.venv/ as the local Python virtual environment
.env as the local machine-specific environment file when runtime configuration is needed
.env.example as the checked-in template for required environment variables

Rules:

create .venv/ at the repo root for Python work rather than using a scattered or global environment
never commit .venv/
never commit a real .env
keep .env.example in sync with any required runtime variables
if no environment variables are currently needed, keep .env.example present as a placeholder with a short comment
when bootstrapping this repo or a fresh clone, set up .venv/ first before running scripts or tests

Compliance manifest defaults

For this runnable workflow repo:

keep the canonical latest compliance manifest at runs/manifests/compliance.latest.json
keep a root-level mirror at compliance.latest.json
keep timestamped compliance snapshots in runs/manifests/
update the latest and snapshot manifests after meaningful governance or verification passes

Canonical file names

Use these exact names wherever relevant.

Study-level

study.yaml

Design

research-plan.yaml
segmentation-analysis.yaml
archetypes.yaml
digividual-profiles.yaml
interview-guide.md
screener.md
recruitment-criteria.yaml
survey-instrument.md

Fieldwork

outreach-log.csv
interview-schedule.csv
respondent-data.csv

Analysis

extracted-profiles.yaml
coded-themes.yaml
quotes.yaml
segment-comparisons.yaml
insights.yaml
codebook.yaml
cross-tabs.yaml
statistical-summary.yaml
secondary-source-register.yaml
secondary-source-extracts.yaml
grounding-map.yaml

Outputs

report.yaml
summary.yaml
data-summary.yaml
report.md
summary.md
presentation.md
data-summary.md

Do not create near-duplicates such as:

research_plan.yaml
segmentation.yml
personas.yaml
final-report-v2.md

Study slug rules

Study slugs must be:

lowercase
words separated by hyphens
descriptive but concise

Examples:

medical-night-shift-workers
parents-bedtime-books
urban-gen-z-savers

Do not use spaces, underscores, dates, or vague names like study1.

Canonical concepts

Use these concepts consistently:

research_plan for the design rationale and study goals
segmentation_analysis for segmentation framing and justification
archetypes for reusable segment definitions
digividual_profiles for synthetic or structured exemplar profiles
attributes for descriptive behavioral or contextual fields
personality_traits for Big Five traits on a 1-5 scale when available
notes for uncertainty, caveats, ambiguity, or partial reconstruction

Evidence and behavioral rules

Always preserve the distinction between:

audience
segment
archetype
digividual
participant
interviewee
transcript
quote
coded theme
insight

These are not interchangeable.

Do not collapse design into evidence:

a digividual profile is not evidence
an archetype is not evidence
a transcript is evidence
a quote is evidence
a coded theme is analysis
an insight is synthesis

Do not silently rewrite user intent. If normalizing structure, explain the reason briefly.

Do not fabricate fieldwork artefacts. Never invent:

transcripts
quotes
interview dates
recruitment outcomes
participant consent

You may create placeholders or clearly marked synthetic examples only when the user explicitly wants that.

Standard workflows

Workflow 1: Create a new study

When creating a new study:

create studies/<study-slug>/
create design/, fieldwork/, analysis/, outputs/, and logs/
populate canonical files from templates/
create study.yaml
validate the structure

Minimum viable new study:

study.yaml
design/research-plan.yaml
design/segmentation-analysis.yaml
design/archetypes.yaml
design/digividual-profiles.yaml
design/interview-guide.md

Workflow 2: Add or refine segmentation

When working on segmentation:

update design/segmentation-analysis.yaml
keep archetypes.yaml separate from the rationale
ensure each archetype has a clear name, criteria, goals, and interview coverage

Do not bury archetypes inside segmentation-analysis.yaml unless the user explicitly asks for that structure.

Workflow 3: Add or refine digividuals

When generating digividuals:

store them in design/digividual-profiles.yaml
use the canonical structure with full_name, demographics, attributes, personality_traits, and notes
mark uncertain traits as null or describe uncertainty explicitly

Workflow 4: Analyse transcripts or respondent evidence

When analysing evidence:

never overwrite raw transcripts or raw respondent data
store raw artefacts under fieldwork/
store structured outputs under analysis/
keep quotes, themes, profiles, comparisons, and insights in separate canonical files where possible

Workflow 5: Build grounded outputs

When generating summaries or reports:

pull only from design artefacts, fieldwork evidence, and analysis artefacts
do not introduce unsupported claims
keep report.yaml, summary.yaml, and data-summary.yaml as the canonical structured sources when present
render markdown outputs from the structured sources rather than treating markdown as the only source of truth

Workflow 6: Source grounding

When a study includes secondary research grounding:

track sources in analysis/secondary-source-register.yaml
store extracted evidence in analysis/secondary-source-extracts.yaml
map claims to evidence in analysis/grounding-map.yaml
clearly distinguish sourced evidence from synthetic hypotheses or strategic interpretation

Output and quality rules

Before treating work as complete, check that:

artefacts are in the canonical locations
file names match the repo contract
unsupported claims are removed or marked
uncertainty is explicit where needed
design, evidence, analysis, and output layers remain distinct
local environment setup is documented when new runtime dependencies or environment variables are introduced
repo compliance manifests are updated after a meaningful compliance pass
validation scripts or tests still pass after structural changes

Final rule

Keep the repository portable, study-centric, and evidence-aware. Prefer consistency over novelty. 3. ensure outputs clearly distinguish:

observed evidence
interpretation
recommendation

Validation rules

Before considering work complete, validate:

Structural validation

canonical file names used
study folder structure correct
YAML parses
Markdown files exist where expected

Semantic validation

no mixing of archetypes and raw participant evidence
no unexplained uncertainty
no unsupported insight claims
no brand/persona terminology drift unless intentionally part of the study

Naming validation

correct study slug
correct YAML top-level keys
no duplicate or near-duplicate files

Output validation

exports align to source YAML
reports reflect actual study scope
notes are preserved where reconstruction occurred

Preferred commands

Use project scripts when they exist.

Typical commands should include:

initialize a study
validate YAML
export YAML to JSON
generate report bundles
run tests

If scripts exist in scripts/, prefer those over ad hoc one-off logic.

When changing scripts, run relevant tests in tests/.

Definition of done

A task is done only when all of the following are true:

The requested files are created or updated in the correct canonical locations.
File names follow repo conventions exactly.
YAML is valid and structurally consistent.
Evidence and synthesis are not mixed improperly.
Notes are added where content is uncertain or reconstructed.
Relevant validation or tests have been run if available.
The result is usable by the next human or agent without guessing.

Writing style for repo content

For YAML

prefer stable, explicit keys
prefer readable nesting over clever compression
use null rather than empty guesswork
use multiline > blocks for long descriptions

For Markdown

write clearly and directly
prefer short sections with meaningful headings
avoid hype language
be explicit about assumptions and limitations

For reports

distinguish evidence from interpretation
use quotes carefully
do not overclaim
preserve methodological transparency

Research quality guardrails

Good practice

segment based on meaningful differences
make archetypes actionable
keep digividuals plausible and bounded
use quotes and themes to support insights
preserve provenance from transcript to synthesis

Bad practice

inventing participant evidence
treating archetypes as real participants
overfitting segments around weak assumptions
collapsing uncertainty into fake precision
producing polished outputs unsupported by actual fieldwork

If unsure, prefer this decision logic

When uncertain:

preserve source material
choose the canonical repo structure
note uncertainty explicitly
avoid inventing evidence
keep design, evidence, analysis, and output separate

Agent-specific expectations

When acting as a coding or research operations agent in this repo:

be systematic
prefer reusable structure over one-off convenience
keep the repository tidy
reduce ambiguity for future agents
leave behind validated, understandable artifacts

This repo is intended to function as a long-lived research system, not just a file dump.

About