shinpr LLM-Friendly Context
Purpose
Use this skill when writing or revising any content another agent will execute or judge: prompts, handoffs, planning artifacts, review findings, completion reports, generated instructions, test skeleton comments, work plans, and task files.
The goal is stable downstream execution. The next agent should know the target action, required inputs, accepted decisions, observable success criteria, and the condition that requires escalation.
Core Rules
Use positive, executable instructions
- State the action the next agent should perform.
- Convert quality policies into observable acceptance 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.
Resolve outcome-relevant ambiguity
- Clarify an instruction when plausible interpretations would change correctness, requested scope, downstream usability, or verification. Use the least-restrictive sufficient condition, source, or example.
- Leave local, reversible choices to the next agent when the stated outcome, constraints, and repository evidence are sufficient to choose. A subjective word alone does not require another rule or decision.
Specify output shape
- Define only the sections or fields the next consumer uses.
- For agent handoffs, name produced artifact paths and the result needed by the next action. Require exact serialization only when a program parses it.
Provide necessary context
- Include purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions.
- Prefer concrete file paths and section hints over broad module names.
- Follow references only while they can change an in-scope decision, action, or verification result.
Decompose complex work into verifiable steps
- Expose dependency order when a later action relies on an earlier result.
- Reuse one execution plan to retain all required steps and final verification during multi-step work. Simple, single-action work proceeds directly.
Permit uncertainty explicitly
- State missing, contradictory, or unverifiable source material and its effect on the current action.
- Return unresolved decisions to the orchestrator with the evidence needed to resolve them; the orchestrator decides whether user input is necessary.
Keep constraints proportionate
- Add constraints that reduce ambiguity or preserve a real requirement.
- Keep simple downstream tasks lightweight when target action, context, and success criteria are already clear.
Rewrite Patterns
Use these rewrites when an ambiguity materially changes the next action or its result. Retain valid local choices within the stated boundaries.
| Ambiguous form | Rewrite as |
|---|---|
optional used as an unresolved choice |
Required, omitted, or required only under a named condition |
| Alternatives with different scope or contract effects | The accepted decision, or the evidence boundary within which the agent may choose |
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 or behavior, allowed dependencies, and verification expectation |
TBD used for required information |
A blocking unresolved item with owner, required input, or escalation condition |
appropriate / proper with materially different interpretations |
The observable success criterion that distinguishes acceptable results |
Handoff Checklist
Before sending a prompt or artifact to another agent, verify:
- The target action is explicit.
- Required input paths and source artifacts are named.
- Accepted decisions and constraints are stated once with stable wording.
- The next consumer can identify the artifact or result it needs.
- Success criteria are observable.
- Outcome-relevant ambiguities are resolved or identified with their effect; valid local choices remain available.
- Every retained prohibition names the protected condition and allowed alternative.
- Dependencies needed by the next action are visible.
- The next agent can complete its scope or return the unresolved decision with evidence.
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.
- Every retained prohibition names the protected condition and allowed alternative.
- Derived artifacts preserve copied decisions with the same wording and meaning as their source artifacts.
- Blocking missing information records the missing input and escalation condition.
References
- Task File Contract — execution-carrier fields and filename routing for task-decomposer, build recipes, and Small flows