diff --git a/.changeset/improve-authoring-guidance.md b/.changeset/improve-authoring-guidance.md new file mode 100644 index 00000000..d1308cd0 --- /dev/null +++ b/.changeset/improve-authoring-guidance.md @@ -0,0 +1,5 @@ +--- +"@design-intelligence/ghost": patch +--- + +Strengthen the bundled authoring recipe with public guidance for confirming decisions, comparing supplied materials, and making the smallest complete package change. diff --git a/packages/ghost/src/skill-bundle/references/authoring.md b/packages/ghost/src/skill-bundle/references/authoring.md index 18b96d9c..86b66e76 100644 --- a/packages/ghost/src/skill-bundle/references/authoring.md +++ b/packages/ghost/src/skill-bundle/references/authoring.md @@ -3,11 +3,12 @@ name: authoring description: Create or update a ghost package through human elicitation, evidence inspection, confirmation, and validation. --- -# Recipe: Author A ghost Package +# Recipe: Author a ghost Package **Goal:** turn human intent and supplied evidence into a small, durable `.ghost/` -package. Agent synthesis is draft work. Human confirmation and ordinary Git -review decide what becomes canonical. +package. A package contains decisions, not guesses. Agent synthesis is draft +work until the human confirms it, and ordinary Git review decides what becomes +canonical. ## Start from the package state @@ -15,20 +16,34 @@ Use one workflow with a different first move: | Starting state | First move | | --- | --- | -| No package | Run `ghost init`, then capture one repeated decision. Do not attempt the whole brand. | +| No package | Run `ghost init`, inspect the complete starter, then capture one decision. Do not hand-create a smaller package or attempt the whole brand. | | Existing package | Run `ghost validate`, `ghost gather "update the package"`, and pull potentially affected nodes before proposing edits. | | Starter package | Treat every inherited answer as provisional until the owner replaces or accepts it. Change the manifest id only when the human takes ownership. | A monorepo or product suite uses one contract per package. Do not invent a hierarchy between packages. +When no package exists, `ghost init` is required. Do not hand-create the +manifest, glossary, cover, or starter structure to make the first change +smaller. Inspect every initialized file before proposing edits. Treat inherited +answers as provisional, but do not silently omit or replace them. Keep the first +confirmed brand decision small, not the package scaffold. + ## The authoring loop ### 1. Orient -Ask for the decision whose feedback keeps repeating: the checkout always -flagged for trust, the voice always re-toned, the empty state always rewritten. -One grounded node beats an empty catalog and a broad first pass. +Start by reviewing what the human shared, then name one likely decision to +clarify first: for example trust in checkout, voice in product copy, or +empty-state guidance. One clear node is more useful than a broad first pass. + +When starting from nothing, do not begin with a questionnaire. Ask for any +material that shows the brand: guidelines, screenshots, links, design files, +colors, fonts, product surfaces, copy examples, or rejected work. It does not +need to be organized. Review and sort what the human supplies, explain what +ghost could learn from it, ask only where an important choice is unclear, +recommend what to add and what to leave out, then ask for approval before +writing package files. Interview only for answers that change guidance: @@ -65,7 +80,9 @@ Keep observations outside `.ghost/`, normally in the conversation. Separate: 3. **Confirmed guidance:** the human confirms the decision, condition, and scope. Only the third may enter node prose. Never claim an unopened artifact was -inspected. Repetition supports a question, not an inference of intent. +inspected. Repetition supports a question, not an inference of intent. Separate +intended decisions from implementation details, old choices, exceptions, and +accidents. ### 3. Reconcile before adding @@ -81,14 +98,37 @@ Compare each proposed decision with pulled guidance: | Implementation-only | add a material locator only when existing prose already explains its purpose | | Incidental or generic | no package change | +When comparing an outside guideline, document, or example set with an existing +package, classify each meaningful decision as already covered, covered but +unclear, missing, inconsistent, or unsupported. Do not copy a document into the +package. Remove repetition, generic advice, stale implementation details, and +language that does not change a future choice. Ask about conflicts and unclear +claims. Add only decisions the human confirms. + Prefer, in order: no change, material locator, existing-node edit, new node, then split, rename, or removal. A new node is not a dumping ground for evidence. Contradictions are never resolved silently. +Choose the smallest effective form: + +- Use prose for priorities, choices, conditions, and reasons. +- Use `materials` when a concrete file makes guidance exact or inspectable. +- Use an example when several decisions need to be seen together; explain what + matters so it is not copied blindly. +- Use a `## Skeleton` only when relevant work must begin from that structure. +- Use a rejection only when it prevents a likely harmful choice and gives the + preferred alternative. + +If clearer wording fixes the problem, rewrite existing guidance. If an exact +value is being invented, reference the token or material that owns it. If +existing guidance was clear and available, do not add another rule. + ### 4. Propose the smallest useful diff Before editing, present a short proposal with the evidence, affected node, -verdict, proposed change, and choice needed. The human may accept, correct, +verdict, proposed change, and choice needed. Smallest refers to the authored +brand decision, not permission to bypass required package scaffolding. The human +may accept, correct, narrow, reject, mark legacy, or defer it. Write only accepted changes. Restate the final form after a correction or narrowing. @@ -96,6 +136,10 @@ When no package exists, the first proposal should usually be one cover decision or one node, not a completed taxonomy. Grow the package when the next repeated decision appears. +Rank proposed changes by consequence. Lead with changes that affect brand +recognition, accessibility, accuracy, trust, or a central product decision. Let +minor differences go when they do not justify more guidance. + ### 5. Write and confirm Use [nodes.md](nodes.md) for node craft, [materials.md](materials.md) for material @@ -105,6 +149,20 @@ Keep each edit attributable to something the human said, showed, or accepted. Ask the human to keep, soften, narrow, reject, or mark important claims as legacy. Uncommitted edits remain drafts. Git review is the approval boundary. +Treat each edit as a complete package change: + +- State each decision once, in exactly one node. +- Check the cover and related nodes for duplication or conflict. +- Ensure each edited node still works when pulled independently. +- Update affected material declarations, glossary entries, manifest pointers, + and checks. +- Keep checks as review assertions. Never let a check introduce guidance absent + from its referenced node. + +Before moving or deleting guidance, account for every original decision. A topic +still appearing somewhere is not proof the decision survived. Move each decision +to the right place or deliberately remove it, then explain why. + ### 6. Validate ```bash @@ -113,7 +171,8 @@ ghost validate Fix errors. Treat warnings as decisions to resolve, not output to hide. Present the final package diff and call out contradictions that were kept, conditioned, -replaced, or deferred. +replaced, or deferred. Validation confirms package shape; it does not confirm +that a brand decision is correct. ## Adapting a starter @@ -136,10 +195,15 @@ itself. Until adaptation finishes, identify starter guidance as provisional. ## Never +- Never hand-create a package when `ghost init` can initialize it. - Never derive brand guidance from code, frequency, or a brand deck alone. +- Never turn an observation into a brand decision without confirmation. +- Never invent a value to fill a gap; ask for a decision or leave it out. - Never put unconfirmed observations or scratch notes in `.ghost/`. - Never regenerate an existing package because new evidence arrived. - Never resolve a contradiction silently. - Never create a new node when a focused edit preserves the existing purpose. +- Never write a prohibition without the preferred alternative. +- Never let a check create guidance that its referenced node does not state. - Never let an agent automate the starter manifest-id change; ownership is a human act. diff --git a/packages/ghost/src/skill-bundle/references/nodes.md b/packages/ghost/src/skill-bundle/references/nodes.md index 0143ed7b..5c3ebe97 100644 --- a/packages/ghost/src/skill-bundle/references/nodes.md +++ b/packages/ghost/src/skill-bundle/references/nodes.md @@ -34,6 +34,11 @@ optional `## Skeleton` (always last): - `## Never` — selective, high-value failure modes, each paired with its replacement: "never X — instead Y." +This is a closed heading set unless the package glossary declares another body +shape. Do not add ad hoc sections for notes, exceptions, sources, or what to do +when guidance is silent. Put a package-wide silence rule in the cover's prose +only when the brand needs to override the host skill's default behavior. + Route each claim to one home. Can a reviewer observe it in the artifact? Rules. Does it reject a plausible move and name the replacement? Never. Does it shape decisions not covered by either? Usage. None of these? Cut it. @@ -68,6 +73,40 @@ lines. Elsewhere, remove filler and unchosen hedges: "elevate," "delight," If the human has not picked a side, return to authoring rather than laundering uncertainty into prose. +## Edit sentence by sentence + +After drafting, tighten the node before presenting it. Use plain, direct +language and keep one idea per sentence. Name the element, decision, condition, +and reason instead of using abstract brand language. + +Read each sentence against the one before and after it. If removing a sentence +keeps the same decision and reason, remove it. If two sentences make the same +point, keep the clearer one. If a sentence only introduces, summarizes, or +repeats the section, cut it. + +Avoid clever labels, metaphors, academic phrasing, and broad design jargon. +Name the specific decision, element, condition, or action instead. Replace vague +phrases with the background, layout, copy, motion, hierarchy, spacing, or +interaction decision the agent must preserve. + +Watch for words that sound precise but hide the actual choice: + +| Instead of... | Name... | +| --- | --- | +| `signal` | the exact cue: color, copy, position, size, motion, contrast, or timing | +| `restraint` | the concrete limit: count, spacing, frequency, contrast, ornament, or emphasis | +| `temperature`, `personality`, or `brand soul` | the observable behavior: tone, pace, density, formality, or visual treatment | +| `worldview`, `standing`, or `provenance` | the decision, source, reason, or authority the agent should use | +| `furniture`, `artifact`, or `thing` | the actual page, screen, document, component, example, or output | +| `taxonomy`, `ladder`, `rung`, `front door`, or `junk drawer` | the file, group, order, entry point, or purpose | +| `carry the field`, `let the signal land`, or similar phrasing | the background, spacing, hierarchy, or emphasis to apply | + +In node prose, rewrite these words when they stand in for the actual +instruction. Name what to change, preserve, avoid, or check. + +Every prohibition needs the preferred alternative. Do not write a blacklist item +unless the node also says what to do instead. + ## Patterns bind and open A pattern fixes part of a reusable structure and leaves the rest available: