Skip to content

heliohq/ship / skills/design

design

Verified

Plan 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.

FileKindSize
SKILL.mdskill md15.9 KB
execution-drill.mdmarkdown3.7 KB
independent-investigator.mdmarkdown5.2 KB
write-plan.mdmarkdown6.0 KB
write-spec.mdmarkdown1.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
```
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: 323kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall