craft-survey

craft-survey

Purpose

Study comparable prompts, skills, or repo assets, extract the best patterns, and turn them into actionable improvements.

A grounded survey matters because agents that invent from scratch often rediscover bad shapes the community has already outgrown. A focused pass through prior art surfaces the handful of patterns that genuinely carry their weight — and, just as importantly, identifies the ones that shouldn't be copied.

Use this when

• there are older assets worth learning from
• a new skill should be grounded in proven patterns
• the current artifact feels under-informed
• best practices should be incorporated without cargo-culting them
• the user asks "how do others do this?" or wants a literature-review pass before committing

Inputs

• target artifact or problem
• local references if available
• optional public references if allowed
• constraints and intended audience

Steps

1. Start with local or in-repo references first. They're closest to the current context and cheapest to verify.
2. Identify comparable assets and group them by purpose. Grouping makes recurring shapes visible.
3. Extract repeated patterns that seem genuinely useful. Prefer patterns that show up across multiple sources.
4. Separate core patterns from optional stylistic choices. Confusing the two is how cargo-culting starts.
5. Synthesize a small set of recommended changes. Synthesis beats quotation — don't just paste from sources.
6. Recommend only the changes that improve clarity, reuse, or quality. Novelty alone isn't a reason to adopt a pattern.

Output format

Survey target

One or two sentences naming the specific artifact being improved and the concrete survey question driving this pass. A reader seeing only this section should know what would count as a useful answer — not a generic "strengthen the artifact."

Reference patterns

Short list of patterns found in comparable assets. Every pattern must cite its provenance — either inline per item, or via a section-opening source map that binds each pattern to its source file + section. A pattern with no traceable source doesn't belong on the list.

Adopt

Patterns worth bringing into CraftKit. Each item is two parts: the pattern (short handle) AND a rationale clause naming a concrete benefit — what failure it prevents, what friction it removes, what quality it raises. Bare phrases don't satisfy the section; they model without grounding.

Avoid

Patterns that should not be copied. Each item is two parts: the pattern AND a rationale clause naming the specific harm — what it breaks, what coupling it introduces, what portability it costs. Bare phrases don't satisfy the section.

Recommended edits

Concrete file or section changes. Each item must name three things: (a) the target file (path or skill name), (b) the specific section/heading/location within that file, and (c) the edit verb (add / tighten / remove / replace / refactor). Scale the number of edits to the scope of the research ask — a narrow question deserves 1–3 edits, not a full rewrite list.

Risks

Survey-specific risks only. At least one risk must reference either the actual source set surveyed or a named constraint of the target artifact. Generic risks that could appear verbatim in any prior-art survey don't count — if the risk is portable across unrelated survey passes, it hasn't engaged this survey.

Guardrails

• prefer first-principles synthesis over copy-paste
• do not import provider-specific quirks into core assets
• cite provenance in docs when relevant
• use a few strong patterns, not a giant laundry list

Failure modes

• treating one strong reference as a template and overfitting to its quirks
• turning the output into a literature review instead of actionable edits
• importing provider-specific phrasing that breaks portability
• skipping the "avoid" list and copying every pattern uncritically

Example

Input

Improve a tuning skill using older prompt-builder assets and meta-skills as references.

Output

Survey target Strengthen the tuning skill so it produces more consistent and portable edits.

Reference patterns

• explicit inputs and outputs — source: skills/craft-autoresearch/SKILL.md § Inputs / Final artifact
• minimal-diff editing — source: skills/craft-prompt/references/shared-principles.md (cut order, right-sized)
• critique before revision — source: skills/craft-critique/SKILL.md § Steps
• examples embedded in docs — source: skills/craft-prompt/references/prompt-patterns.md § Review prompts

Adopt

• revised artifact plus changelog structure — prevents users from receiving edits they cannot audit
• failure-mode note — exposes the conditions where the tuned prompt will still drift
• preservation of original intent — prevents a cleanup pass from silently changing the prompt's job

Avoid

• overly vendor-specific phrases — couples the skill to one runtime and weakens cross-agent reuse
• giant all-in-one instructions — makes the always-loaded SKILL.md harder to inspect and maintain

Recommended edits

• the tuning skill's § Final output — tighten the changelog fields so each entry names changed / why / effect
• the tuning skill's § Failure modes — add a short note about scope drift during repeated edits
• the tuning skill's § Example — replace the generic example with one compact full-loop run

Risks

• the surveyed sources are all CraftKit-adjacent, so the recommendations may overfit to this repo's naming conventions