/llm-friendly-context

name: llm-friendly-context
description: Clarifies inputs, outputs, success criteria, decisions, and unresolved conditions so downstream consumers can execute without guessing. Use when writing or revising LLM-facing prompts, handoffs, planning artifacts, reviews, reports, or generated instructions.

LLM-Friendly Context

The goal is stable downstream execution: the next consumer should know what to read, what to do, what counts as success, and which unresolved decisions can change the result.

Core Rules

1. **Use positive, executable instructions**

• State what the next consumer should do.
• Convert quality policies into positive criteria.
• Keep a prohibition only when it protects an irreversible boundary or shipped contract. Name the protected condition and the allowed action.
• Example: "Preserve existing public API behavior across the documented compatibility cases."

2. **Make vague instructions concrete**

• Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions.
• Terms that often need clarification when they leave a decision to the next consumer: `appropriate`, `proper`, `related`, `existing behavior`, `optional`, `as needed`, `if needed`, `per convention`, unresolved alternatives, `TBD`, `placeholder`.

3. **Specify output shape**

• Use the sections, fields, table columns, JSON keys, or checklist items the consumer uses.
• For handoffs, include only produced artifact paths and status fields that control the next transition.

4. **Provide the smallest sufficient context**

• Sufficient means sufficient for the assigned action, not complete background: every item you include is consumed by that action or by the result it must produce.
• Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions that action consumes.
• Prefer concrete file paths and section hints over broad module names.
• Follow references while they can change an in-scope decision, action, or verification result.

5. **Decompose complex work into verifiable steps**

• Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task.
• Each step needs a checkpoint: what evidence proves it is complete.

6. **Permit uncertainty explicitly**

• Resolve missing operational detail from referenced artifacts and repository evidence before treating it as unresolved.
• Record remaining uncertainty with its effect, required input, and decision owner. Make reversible repository-local choices when governing evidence resolves them.

7. **Keep constraints proportionate**

• Add only constraints that reduce ambiguity or preserve a real requirement.
• Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear.
• Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count.

Rewrite Patterns

Use these rewrites before treating a prompt, handoff, or artifact as complete.

| Ambiguous form | Rewrite as | |---|---| | `optional` used as an unresolved choice | Required, omitted, or required only under a named condition | | Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria | | `as needed` / `if needed` | The triggering condition and required action | | `per convention` | The file, function, test, or documented convention to follow | | `related files` | Specific paths, globs, or search hints | | `existing behavior` | The observable behavior, source file, test, API response, or UI state to preserve | | `placeholder` | Exact temporary value/behavior, allowed dependencies, and verification expectation | | `TBD` used as a placeholder for required information | A blocking unresolved item with owner, required input, and decision effect | | `appropriate` / `proper` | A measurable criterion or checklist |

Handoff Checklist

Before sending a prompt or artifact to another consumer, verify:

• [ ] The target action is explicit.
• [ ] Required input paths, source artifacts, and decision-relevant facts are named.
• [ ] Every included context item is consumed by the target action or its required result.
• [ ] Accepted decisions and constraints use one canonical wording.
• [ ] Output format or expected status fields are specified.
• [ ] Success criteria are observable.
• [ ] Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains.
• [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative.
• [ ] The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner.

Generated Artifact Checklist

Before writing or finalizing a generated document:

• [ ] Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists.
• [ ] Every executable instruction names the target, action, and expected result.
• [ ] Verification steps say what to run or observe and what result proves success.
• [ ] Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative.
• [ ] If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning.
• [ ] If downstream work is blocked by missing information, the artifact records the missing input, decision owner, and effect.