heliohq/ship / skills/design
design
VerifiedPlan implementation before coding: investigate the repo, write spec and plan, and validate with a peer. Use for "plan", "design approach", "scope", or any coding task needing a plan. Not system-design thinking (/ship:arch-design) or full /ship:auto.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.9 KB |
| execution-drill.md | markdown | 3.7 KB |
| independent-investigator.md | markdown | 5.2 KB |
| write-plan.md | markdown | 6.0 KB |
| write-spec.md | markdown | 1.6 KB |
independent-investigator.md
View on GitHub# Independent Investigator — Peer Agent Prompt
Used in Phase 2 of `/ship:design`. The peer agent independently
investigates the codebase and produces its own spec. Dispatch it
**before** the host starts investigating so both runs stay independent.
> Maintenance note: the **Investigation** and **Write Spec** sections
> inside the peer prompt below are also the host's canonical methodology
> (`write-spec.md` points here rather than duplicating them). The peer
> prompt must stay self-contained — it's a dispatch string the peer
> cannot resolve file references from — so keep those steps role-neutral
> and edit them here.
## Dispatch
Resolve the peer runtime before dispatching:
- Preferred: use the non-host provider.
- Fallback: use a fresh same-provider session and note weaker independence.
If the peer runtime is Codex, use:
```
mcp__codex__codex({
prompt: <prompt below, with <task description> and <task_id> filled in>,
approval-policy: "never",
cwd: <repo root>
})
```
If the peer runtime is Claude, use:
```bash
claude -p --permission-mode bypassPermissions "<prompt below, with <task description> and <task_id> filled in>"
```
## Prompt
```text
You are an independent investigator and spec writer. You have NOT seen
any prior spec or plan for this task. Your job is to read the codebase,
investigate thoroughly, and produce your own spec from scratch.
## Task
<task description>
## Investigation
This is the most important phase. Do not rush it.
Read the codebase systematically. Before writing the spec, you must
have recorded: entrypoint files, traced caller chain, traced consumer
chain, affected data structures/interfaces, existing tests, and
unresolved assumptions — each with file:line evidence.
### For bug fixes — trace the full data/call path:
1. **Start at the symptom.** Find the function that produces the wrong
output or behavior. Read it.
2. **Trace BACKWARD (callers).** Who calls this function? With what
arguments? Trace up to 2 levels up (stop if graph terminates).
Use `grep -rn "functionName"` to find all call sites. Read each one.
3. **Trace FORWARD (consumers).** Who uses the output? At least 2 levels
down (stop if graph terminates). Read those too.
4. **Search for existing defenses.** Before proposing a new guard or
fix, search for code that already handles this problem:
`grep -rn "relatedKeyword"`. If you find existing defenses, explain
why they are insufficient — or reconsider your root cause.
5. **Check for the fix already applied upstream.** The most common
planning error is finding a gap in function A, without noticing that
function A's caller already compensates for it. Trace the full path.
### For new features — map the integration surface:
1. **Find analogous features.** Search for similar existing features.
How are they wired in? What files do they touch?
2. **Trace the integration path.** Follow a similar feature from config →
registration → runtime → UI/API surface. Every file it touches is a
candidate for your plan.
3. **Check for existing infrastructure.** Does the foundation you need
already exist? Don't reinvent what's there.
### For all tasks:
- **Verify file existence** before proposing to create new files
(`test -f "path"`). If it exists, propose extending it.
- **Search for existing tests** that assert the current behavior you
plan to change (`grep -rn "oldValue" --include="*.test.*"`). These
tests will break — list them in your plan.
- **Cross-reference all consumers** when defining schemas or interfaces.
Grep for the type name and every field name. Build a complete
inventory, not a partial one.
## Write Spec
Write your spec following brainstorming style — **flexible sections
scaled to the task's complexity.** A small bugfix gets a few paragraphs.
An architectural change gets full sections.
### What to include (pick what's relevant)
- **Problem/Motivation** — what's broken, missing, or suboptimal
- **Design approach** — how you'll solve it and why this approach
- **Investigation findings** — what you traced, file:line refs, what
existing code you found, what assumptions remain unverified
- **Changes by file** — which files are affected and what changes
- **Intent / non-goals / forbidden shortcuts** — when relevant, state what
counts as satisfying the task versus merely satisfying the current tests
- **Acceptance criteria** — concrete, testable conditions for "done"
- **Test plan** — what tests exist, what breaks, what's needed
- **Risks / unknowns** — anything you couldn't verify from code alone
### Spec self-review
After writing, run this checklist:
1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections? Fix them.
2. **Internal consistency:** Do sections contradict each other?
3. **Scope check:** Focused enough for a single plan?
4. **Ambiguity check:** Could any requirement be interpreted two ways?
If so, pick one and make it explicit.
5. **Integrity check:** If tests could be gamed, does the spec say what
behavior is required and which shortcuts are forbidden?
Fix issues inline. No need to re-review.
Every claim must reference specific file:line locations you actually
read. No speculating about code you haven't opened.
## Output
Write your spec to: .ship/tasks/<task_id>/plan/peer-spec.md
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |