frankgpt/Legacy/_Frank_/markdown/style.craft.instructions.md

description: "Defines the C.R.A.F.T. framework (Context, Role, Action, Format, Tone/Audience) and provides templates, examples, and an author checklist for crafting prompts." applyTo: "**"

The C.R.A.F.T. Framework

All prompt generation, analysis, and refactoring must be performed through the lens of the C.R.A.F.T. framework.

• Context: Background, inputs, and constraints the model needs to understand the task.

• Role: The persona or skill the model should adopt (expert, teacher, analyst, etc.).

• Action: A single, clear imperative describing what the model should do.

• Format: The exact output structure (schema, file type, or layout) required.

• Tone / Audience: The writing style and the intended reader (e.g., "concise for executives").

---

description: "Defines the C.R.A.F.T. framework (Context, Role, Action, Format, Tone/Audience) and provides templates, examples, and an author checklist for crafting prompts."

applyTo: "\*\*"

---

## The C.R.A.F.T. Framework

All prompt generation, analysis, and refactoring must be performed through the lens of the C.R.A.F.T. framework.

- **Context:** Background, inputs, and constraints the model needs to understand the task.

- **Role:** The persona or skill the model should adopt (expert, teacher, analyst, etc.).

- **Action:** A single, clear imperative describing what the model should do.

- **Format:** The exact output structure (schema, file type, or layout) required.

- **Tone / Audience:** The writing style and the intended reader (e.g., "concise for executives").

## Purpose and scope

This file provides a prescriptive template and practical guidance for writing prompts used in `.prompt.md`, `.chatmode.md`, and other instruction-oriented Markdown files. Use the minimal template for short one-off prompts and the extended template for complex or reusable prompts.

## Minimal CRAFT prompt template (copy & fill)

Context: ${short context — 1–2 sentences describing input, environment, constraints}

Role: ${persona — e.g., "Senior Data Scientist"}

Action: ${single imperative verb + brief object — e.g., "Summarize the report into 5 bullet points"}

Format: ${output form — e.g., "Markdown numbered list" or "JSON: {summary, details}"}

Tone / Audience: ${tone and audience — e.g., "plain English for product managers"}

Example (minimal):

Context: You are given a 10-page product requirements document about a new payments feature.

Role: Product manager summarizer.

Action: Extract the top 6 functional requirements and the 3 main risks.

Format: Markdown with H2 sections "Requirements" and "Risks" and numbered lists underneath.

Tone / Audience: Executive-level, concise.

## Extended CRAFT template (for complex or reusable prompts)

Include the minimal template plus these fields when the task is non-trivial or will be reused.

- Inputs: Named inputs expected by the prompt (e.g., `file: report.md`, `variables: {start_date, end_date}`).

- Constraints: Hard limits and rules (e.g., "max 150 words", "no invented facts", "must include citations").

- Examples: 1–2 minimal input → output examples showing exact format and level of detail.

- Verification: How outputs will be checked (simple rubric, unit test, or follow-up verification prompts).

- Metadata: Optional changelog, author, and `applyTo` recommendations for `.instructions.md` files.

Extended example:

Context: You have a CSV of customer support tickets with columns {id, created_at, category, resolution_time, text}.

Role: Senior analyst who writes reproducible summaries.

Action: Produce an executive summary of trends for the prior quarter and recommend 3 operational changes.

Format: 1) A 3-paragraph executive summary (max 150 words). 2) A Markdown table of top 5 categories and their avg resolution_time. 3) A numbered list of 3 recommendations.

Tone / Audience: Non-technical VP of Support; use plain English and define any domain terms.

Inputs: `file: tickets_q3.csv`

Constraints: Do not extrapolate outside the data. Include the exact SQL used to compute the table (one-line code fence). Max 150 words for the executive summary.

Examples:

- Input: (small sample rows) → Output: (example summary)

Verification: Check that the table rows match results from the provided SQL.

## Quick author checklist (pre-submit)

- [ ] Context gives necessary background and scope (who, what, when, where).

- [ ] Role is an actionable persona (one sentence) and matches desired expertise.

- [ ] Action is a single, clear imperative (avoid compound verbs like "analyze and decide").

- [ ] Format is machine- or human-readable and unambiguous (include a schema when needed).

- [ ] Tone/Audience is specified and consistent with examples.

- [ ] Inputs and Constraints are explicit for any data-driven task.

- [ ] Examples (if present) are minimal, representative, and follow the expected output format.

- [ ] Verification steps or acceptance criteria are stated (e.g., "3 bullets, each <= 20 words").

## Common failure modes and mitigations

- Failure: Model ignores provided inputs or tools.

Mitigation: Make Role explicitly state "You must use the provided inputs/tools and must not hallucinate" and add a Verification step.

- Failure: Output format drift (e.g., prose instead of JSON).

Mitigation: Provide a strict schema and a minimal example JSON instance; instruct "Return only valid JSON".

- Failure: Overly long responses.

Mitigation: Add a hard constraint like "Max 150 words" and show a short Format example.

## Small reusable prompt snippets

Use these snippets to speed prompt authoring and reduce errors. Replace variables in braces.

- "If you cannot answer from the inputs, respond with exactly: 'I don't know based on the provided data.'"

- "Return only valid JSON conforming to this schema: {\"summary\":string, \"items\": [ {\"id\":int, \"note\":string} ] }"

- "Cite the source line or file for any factual claim in the format: (source: <filename>:<line-range>)"

## Evaluation rubric (prompt quality)

Score the prompt before reusing it.

1 — Poor: Missing components; likely to produce ambiguous results.

2 — Fair: Most components present but missing constraints or examples.

3 — Good: Complete CRAFT, includes constraints and short examples.

4 — Excellent: Complete CRAFT, includes verification rules, example outputs, and explicit anti-hallucination language.

## Implementation notes for `.instructions.md` files

- Keep YAML frontmatter (`description`, `applyTo`) accurate and concise.

- `applyTo` should be as specific as practical (e.g., `"**/*.prompt.md"` or `"docs/**"`).

- If this instruction file is also a template, add a short example prompt at the bottom of the file inside a fenced block and maintain a changelog comment at the top.

## References and source materials

This guidance draws on research and practitioner summaries in `Training Guides/Updating CRAFT/` and the CRAFT (toolset) paper by Yuan et al. (ICLR 2024). Use those materials for deeper background when creating complex, reusable prompts.

## Contact and iteration

When you iteratively improve a prompt template, add a one-line changelog at the top with date and reason. Small iterative changes are encouraged.