diff --git a/.changeset/steering-fingerprint-docs.md b/.changeset/steering-fingerprint-docs.md new file mode 100644 index 00000000..7e7ffc4f --- /dev/null +++ b/.changeset/steering-fingerprint-docs.md @@ -0,0 +1,5 @@ +--- +"@anarchitecture/ghost": patch +--- + +Document how to author fingerprints as steering guidance for generation. diff --git a/apps/docs/src/content/docs/fingerprint-authoring.mdx b/apps/docs/src/content/docs/fingerprint-authoring.mdx index ef2c89e8..8157c6b0 100644 --- a/apps/docs/src/content/docs/fingerprint-authoring.mdx +++ b/apps/docs/src/content/docs/fingerprint-authoring.mdx @@ -97,6 +97,31 @@ Keep each claim in the file that will make it useful later: + + +A useful fingerprint should help future agents choose, restrain, route, anchor, +and review. It should not only describe what exists or collect every available +style detail. + +Write layer content so generation decisions become explicit: + +- `goals` name what generated work should preserve. +- `anti_goals` block plausible defaults that would make the surface feel + generic or wrong. +- `tradeoffs` say which value wins when choices conflict. +- `situations` route guidance by task, surface type, state, or audience need. +- `principles` capture broad product intent. +- `experience_contracts` turn taste, trust, recovery, or disclosure into + obligations. +- `composition.patterns` give repeatable layout, flow, state, content, + behavior, or visual rules. +- `inventory.exemplars` anchor the guidance in concrete material an agent can + inspect. + +Write less like a brand book and more like a decision engine. + + + Nested fingerprints are opt-in. Create a local `.ghost/` only when a surface diff --git a/docs/fingerprint-format.md b/docs/fingerprint-format.md index eaeb27cb..51b97481 100644 --- a/docs/fingerprint-format.md +++ b/docs/fingerprint-format.md @@ -62,6 +62,10 @@ Use prose for durable claims about audience needs, product obligations, acceptable tradeoffs, what the surface refuses to become, and contracts that should shape agent behavior. +High-quality layer content makes generation choices explicit: what to preserve, +what to avoid, which tradeoffs win, which situations route guidance, and which +exemplars ground the claim. + `inventory.yml` points to curated material and optional source links: ```yaml diff --git a/packages/ghost/src/skill-bundle/references/capture.md b/packages/ghost/src/skill-bundle/references/capture.md index e0b3b045..95e69534 100644 --- a/packages/ghost/src/skill-bundle/references/capture.md +++ b/packages/ghost/src/skill-bundle/references/capture.md @@ -121,6 +121,10 @@ Treat generated cache as scratch material. Do not copy raw inventory into Edit the smallest useful durable layer content: +- Before writing, ask whether the draft will help future agents choose what + matters most, avoid plausible-but-wrong defaults, resolve competing + priorities, route guidance by situation, inspect concrete exemplars, and + review whether generated work preserved the intended experience. - `prose.yml`: summary, situations, principles, and experience contracts. - `inventory.yml`: topology, building blocks, exemplars, and `sources[]` links. - `composition.yml`: rules, layouts, structures, flows, states, content, diff --git a/packages/ghost/src/skill-bundle/references/patterns.md b/packages/ghost/src/skill-bundle/references/patterns.md index 9db6f2eb..178e73e0 100644 --- a/packages/ghost/src/skill-bundle/references/patterns.md +++ b/packages/ghost/src/skill-bundle/references/patterns.md @@ -25,6 +25,13 @@ Add a pattern when it helps a future agent choose or review: - a visual treatment tied to product meaning - a restraint rule that preserves hierarchy, density, trust, or pacing +A strong pattern usually does one of three jobs: + +- selection: it tells the agent what structure, flow, state, content, behavior, + or visual treatment to choose +- restraint: it tells the agent which tempting default to avoid +- review: it gives a future reviewer something observable to check + Do not add a pattern just because a value or component exists. Put raw observations in `.ghost/fingerprint/sources/cache/` or keep them in scratch notes.