Key files

Taxonomy file locations

• TAXONOMY_ROOT: {PRODUCT}/Taxonomy
• Taxonomy Project Spec: {TAXONOMY_ROOT}/Taxonomy_Spec.md (this document)
• Taxonomy Product Current State: {TAXONOMY_ROOT}/Taxonomy_State.md
• Taxonomy Schema: {TAXONOMY_ROOT}/Schemas/Taxonomy_Schema.ts
• Taxonomy Quality Control: {TAXONOMY_ROOT}/Scripts/Taxonomy_QC.ts
• Taxonomy CSV: {TAXONOMY_ROOT}/Output/Taxonomy.csv
• Taxonomy Map CSV: {TAXONOMY_ROOT}/Output/Taxonomy_Map.csv
• Life Domains: {PRODUCT}/Life_Domains/Output/Life_Domains.json
• Domain Quizzes: {PRODUCT}/Domain_Quiz/Output/

CSV format

Taxonomy.csv

Semicolon-delimited, with header row:

domain;type;id;name;description;tags

Field	Rules
domain	One of the valid LifeDomainId values (see Domains below)
type	One of: issue, aspiration, practice
id	snake_case, unique across entire taxonomy, descriptive short identifier, max 32 characters
name	Human-readable name, 1–50 characters
description	Brief description of the item
tags	Curly-brace-wrapped, comma-separated: {tag1,tag2,tag3,...} — typically 5–7 tags

Example row:

body;issue;insomnia;Insomnia;Insomnia or poor sleep quality;{insomnia,poor sleep,sleep quality,circadian rhythm,rest,recovery}

TaxonomyMap.csv

Comma-delimited, with header row:

id,fromId,toId,weight,note

Field	Rules
id	Format: tam_ + 23-char hex string (e.g., tam_c4d83975badeabfdb08d9f3)
fromId	Taxonomy item id — must be an issue or aspiration
toId	Taxonomy item id — must be a practice
weight	Integer 0–100 (currently all 100)
note	Optional free text

Example row:

tam_c4d83975badeabfdb08d9f3,insomnia,sleep_hygiene,100,

Mapping rules:

• Issues map to practices (issue → practice)
• Aspirations map to practices (aspiration → practice)
• Practices do NOT map to other practices
• Each issue/aspiration typically maps to 2–5 practices
• Practices should be from the same domain as the issue/aspiration
• Map IDs must be globally unique

Valid domains

From the LifeDomainId schema:

#	Domain ID	Title
1	body	Body — Health & Fitness
2	mind	Mind — Mental Wellbeing
3	home	Home — Living Environment
4	intimacy	Intimacy — Sex & Romance
5	community	Community — Relationships
6	school	School (conditional)
7	work	Work (conditional)
8	business	Business (conditional)
9	money	Money
10	parenting	Parenting (conditional)
11	caregiving	Caregiving (conditional)
12	play	Play — Leisure & Creativity
13	growth	Growth — Learning & Development
14	purpose	Purpose — Meaning & Legacy
—	general	Special-purpose LifeDomainId (not a domain)

• Conditional domains (Work, School, Business, Parenting, Caregiving) only appear for relevant users.
• general is not a domain — it exists as a LifeDomainId for special circumstances.

Taxonomy types

Type	Purpose	Example
issue	A problem, challenge, or pain point	Insomnia, Anxiety, Clutter
aspiration	A positive goal or desired state	Muscle Gain, Calm Mind, Financial Peace
practice	An actionable method or habit	Sleep Hygiene, CBT Core, Declutter System

Design principles:

• Issues describe what’s wrong — framed as conditions or symptoms
• Aspirations describe what the user wants — framed as outcomes or goals
• Practices describe what to do — framed as actionable methods, skills, or habit systems
• Each domain should have a balanced mix of all three types
• Practices should be concrete enough to guide real behavior change
• Tags should overlap with quiz question tags for cross-referencing

Conventions

1. IDs are snake_case, globally unique across the entire taxonomy, max 32 characters, short but descriptive
2. Names are Title Case, 1–50 characters
3. Descriptions are concise (1 sentence), describe the item from the user’s perspective
4. Tags use lowercase, 5–7 tags per item, wrapped in {...}
5. No trailing spaces in any field
6. Consistent semicolons — Taxonomy.csv uses ; delimiter
7. Consistent commas — TaxonomyMap.csv uses , delimiter
8. Typographic quotes in descriptions: use “” and ’ (not "" and ’)
9. Domain grouping — items in the CSV are grouped by domain, sorted by type (issues → aspirations → practices)
10. Map ID generation — use tam_ + 23-character random hex string

Running the QC checker

cd {TAXONOMY_ROOT}

# Taxonomy Spec
npx ts-node Taxonomy_QC.ts ./Output/Taxonomy.csv

# Validate with map file
npx ts-node Taxonomy_QC.ts ./Output/Taxonomy.csv --map ./Output/Taxonomy_Map.csv

# Validate a specific domain
npx ts-node Taxonomy_QC.ts ./Output/Taxonomy.csv --domain body

Workflow: Review taxonomy for a domain

1. Read LifeDomain.json for domain definitions and tags
2. Load Taxonomy.csv and filter to the target domain
3. Run Taxonomy_QC.ts for structural validation
4. Check coverage:
   • Are all domain tags represented across taxonomy item tags?
   • Does each issue have 2–5 mapped practices?
   • Does each aspiration have 2–5 mapped practices?
   • Are there orphan practices (not mapped from any issue/aspiration)?
5. Cross-reference with the domain’s quiz file if it exists:
   • Do quiz question tags align with taxonomy item tags?
   • Are there taxonomy items not covered by any quiz question?
6. Report findings without making changes

Workflow: Create new taxonomy items

1. Read the domain definition from LifeDomains.json
2. Review existing items for the domain in Taxonomy.csv
3. Research evidence-based issues, aspirations, and practices for the domain
4. Draft items following all conventions above
5. Generate map entries connecting issues/aspirations → practices
6. Generate unique map IDs using tam_ + random hex
7. Run Taxonomy_QC.ts to validate
8. Append new rows to Taxonomy.csv in the correct domain group
9. Append new map rows to TaxonomyMap.csv

Workflow: Update existing taxonomy items

1. Follow the review workflow above to identify changes needed
2. Make targeted edits preserving existing IDs (never rename an ID)
3. If adding new items, ensure IDs are globally unique
4. Update map entries if practice assignments change
5. Run Taxonomy_QC.ts to validate
6. Verify no broken references in TaxonomyMap

Workflow: Validate taxonomy

1. Run Taxonomy_QC.ts on both files
2. Check for:
   • Duplicate IDs
   • Invalid domain or type values
   • Name length violations (>50 chars)
   • Missing or malformed tags
   • Orphan map references (fromId/toId not in taxonomy)
   • Issues/aspirations with no mapped practices
   • Practices mapped from wrong direction
   • Cross-domain mappings (flag but don’t error)
3. Report all warnings and errors

Integration with Domain Quiz

The taxonomy and quiz systems are tightly coupled:

• Quiz tags (in LifeDomains.json) should align with taxonomy item tags
• Quiz questions assess the user’s current state → surface relevant issues
• Low quiz scores in specific areas → recommend matching practices
• High aspirational scores → recommend matching aspiration practices
• The taxonomy provides the “what to do about it” layer for quiz results