# Decision Record: Convert Human Markdown Prompts to CHORUS Role YAML

- Date: 2025-09-06
- UCXL Address: ucxl://arbiter:ops@CHORUS:prompt-migration/#/docs/decisions/2025-09-06-convert-human-prompts-to-roles-yaml.md

## Problem
Human-oriented prompt templates exist as Markdown files under `agentic-ai-prompt-templates/human/`. CHORUS now sources agent role prompts (S) and default instructions (D) at runtime from bind-mounted YAML/Markdown files. We need these human templates available in the new YAML format to configure agents via Docker volume binding without rebuilding images.

## Options Considered
1) Manual conversion of each Markdown file to a YAML role entry
   - Pros: Tight editorial control
   - Cons: Time-intensive, error-prone, hard to keep in sync

2) Automated converter script to parse Markdown sections and emit a consolidated `system_prompt` with metadata
   - Pros: Fast, repeatable, easy to re-run when templates change
   - Cons: Heuristics may miss atypical structures; requires review

3) Store raw Markdown and embed at runtime
   - Pros: No conversion step
   - Cons: Diverges from adopted loader schema, complicates composition and validation

## Decision
Adopt Option 2. Add a utility script `utilities/convert_human_prompts_to_yaml.py` that:
- Reads `agentic-ai-prompt-templates/human/*.md`
- Extracts title, Description, Tools, Use Cases, When to Use
- Constructs `system_prompt` as: "You are <Name>." + Description + Tools + Use Cases + When To Use
- Emits `project-queues/active/CHORUS/prompts/human-roles.yaml` with one role per file, using filename as role ID
- Populates advisory `defaults` (models/capabilities/expertise/max_tasks)

## Impact
- Roles become mountable via `CHORUS_PROMPTS_DIR` (e.g., `-v ../prompts:/etc/chorus/prompts:ro`)
- Agents can select any converted role via `CHORUS_ROLE=<role-id>`
- Future updates to human Markdown can be re-converted by re-running the script

## Rollback
- Remove `human-roles.yaml` from the prompts directory
- Agents will continue to use existing roles (`roles.yaml`) or default instructions only

## Compatibility Notes
- Loader merges by role ID; ensure IDs don’t collide with existing `roles.yaml` (IDs are based on filenames)
- `defaults.md` remains the global instruction source and is unchanged by this migration

## Evidence / References
- Loader & schema: `pkg/prompt/types.go`, `pkg/prompt/loader.go`
- Prompts directory & compose: `prompts/README.md`, `docker/docker-compose.prompts.dev.yml`