Prompt Resolution

# Domain Model: Layered Prompt Resolution System

**Domain ID**: 01
**Phase**: 1 — Deep Domain Modeling
**Depends on**: None — first-pass modeling
**Last updated**: 2026-03-12
**Status**: draft

---

## Section 1: Domain Overview

The Layered Prompt Resolution System is the mechanism by which Scaffold v2 transforms a methodology name, a set of mixin selections, and optional user customizations into a concrete, ordered list of prompt file paths ready for mixin injection and platform adaptation. It implements a three-layer resolution strategy: **base prompts** (shared across methodologies), **methodology overrides and extensions** (methodology-specific replacements or additions), and **prompt customizations** (project-level and user-level overrides that take highest precedence). The system also handles optional prompt filtering based on project traits, extra-prompt integration from config, and frontmatter merging across layers.

**Role in the v2 architecture**: Prompt resolution is the first computational step after `scaffold build` reads `config.yml`. Its output — a list of `ResolvedPrompt` records — feeds directly into the mixin injection system ([domain 12](12-mixin-injection.md)), which performs text transformation on each prompt's content. After mixin injection, the dependency resolution system ([domain 02](02-dependency-resolution.md)) orders the prompts topologically, and platform adapters ([domain 05](05-platform-adapters.md)) transform them into platform-specific outputs. Config validation ([domain 06](06-config-validation.md)) runs before resolution to ensure the inputs are well-formed.

**Central design challenge**: Reconciling four sources of truth — the methodology manifest's `phases.prompts` list, the base/override/extension file directories, the prompt customization directories, and the per-prompt frontmatter — into a single coherent prompt set, with clear precedence rules, well-defined failure modes, and predictable frontmatter merging behavior.

---

## Section 2: Glossary

**base prompt** — A prompt file in the `base/` directory that is shared across methodologies. Base prompts use abstract task verbs and mixin insertion points rather than tool-specific commands.

**methodology** — A named pipeline configuration (e.g., `classic`, `classic-lite`) that defines which prompts to include, in what phases, with what dependencies. Stored as a directory under `methodologies/`.

**methodology manifest** — The `manifest.yml` file within a methodology directory. Declares the pipeline shape: phases, prompt references, defaults, and dependencies.

**override prompt** — A prompt file in a methodology's `overrides/` directory that completely replaces a base prompt of the same name. Referenced with the `override:` prefix in the manifest.

**extension prompt** — A prompt file in a methodology's `extensions/` directory that has no base equivalent — it exists only within this methodology. Referenced with the `ext:` prefix in the manifest.

**prompt reference** — A string in the manifest's `phases.prompts` list that specifies both the source layer and the prompt name. Format: `<prefix>:<name>` where prefix is `base`, `override`, or `ext`.

**prompt slug** — The short name of a prompt, matching the filename without extension (e.g., `tech-stack` from `tech-stack.md`). Used as the key in dependency graphs, state tracking, and cross-references.

**prompt customization** — A user-provided prompt file that overrides a built-in prompt. Project-level customizations live in `.scaffold/prompts/`, user-level in `~/.scaffold/prompts/`.

**resolved prompt** — The final data record for a prompt after resolution: source layer identified, file path determined, frontmatter merged, optional filtering applied. This is the input to the mixin injection phase.

**extra prompt** — A custom prompt listed in `config.yml` under `extra-prompts`. Added to the pipeline alongside built-in prompts, positioned by its own `depends-on` and `phase` declarations.

**source layer** — One of `base`, `override`, `ext`, `project-custom`, `user-custom`, or `extra`. Identifies where a resolved prompt's content originates.

**optional prompt** — A prompt in the manifest marked with `optional: { requires: <condition> }`. Excluded from the resolved set if the condition is not met by the project's traits.

**project trait** — A boolean capability of the project (e.g., `frontend`, `web`, `mobile`, `multi-platform`, `multi-model-cli`) set during `scaffold init` and stored in `config.yml` under `project`. Used to evaluate optional prompt conditions.

**mixin insertion point** — An HTML comment marker in a prompt file (e.g., `<!-- mixin:task-tracking -->`) that the mixin injection system replaces with concrete content. Not part of this domain, but prompt resolution must verify markers are present for configured axes.

**frontmatter** — YAML metadata at the top of a prompt file. Fields include `description`, `depends-on`, `phase`, `argument-hint`, `produces`, `reads`, `artifact-schema`, and `requires-capabilities`.

**built-in prompt** — Any prompt that ships with the scaffold CLI package (base prompts, methodology overrides, and methodology extensions). Distinguished from custom prompts.

---

## Section 3: Entity Model