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
-
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."
-
Make vague instructions concrete
- Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules.
- 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.
-
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.
-
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.
-
Decompose complex work into verifiable steps
- Split work with 3+ objectives or sequential dependencies into ordered steps.
- Each step needs a checkpoint: what evidence proves it is complete.
-
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.
-
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.
- Apply
minimal,a few lines, and explicit line estimates to the completed diff as one total budget.
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 |
| Multiple alternatives that the next consumer must choose between | The selected option, or a deterministic decision rule |
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.
- Ambiguous expressions have been rewritten or marked as unresolved.
- 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.
