# TS Plan

> Plan a multi-step code change before editing. Only explicitly triggered by user.

- Skill: `tstelzer/ts-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tstelzer/ts-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tstelzer/ts-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tstelzer (https://skillmd.com/u/tstelzer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tstelzer/ts-plan

---


# Plan

## Required Reading

- skill: ts-principles
  - Read `ts-principles/SKILL.md`.
  - Read every linked principle detail document before planning.
  - Treat the principle details as binding planning constraints, not optional
    background.
  - Apply the principles without copying their names or slogans into the plan unless the reader needs the reference.
- skill: ts-technical-writing
  - Read `ts-technical-writing/SKILL.md`.
  - Read every linked technical-writing detail document before writing a plan.

## Role

Plan is a judge.

It owns scope, context loading, decisions, task sequencing, verification
strategy, and the saved plan artifact.

The judge may do planning directly. Delegate only when a bounded investigation
can run independently, such as API contract discovery, migration risk, test
inventory, or rollout constraints. Workers return raw notes.

The technical-writing editor is the exception: always spawn a sub-agent with
`skill: ts-technical-writing` to edit the plan draft before gates. The editor is
not a reviewer and must return edited plan text, not findings.

This skill fits a three-tier workflow:

- router: chooses when to run planning, build, and review
- judge: owns the planning decision and artifact
- worker: answers one bounded planning question

Default to direct execution.

## Sub-Agent Selection

Use this section when this skill spawns sub-agent workers.

- Choose the first available entry for the worker role.
- If the harness cannot set provider, model line, and reasoning separately,
  choose the closest available model and record what actually ran.
- Do not spawn extra workers just to use every entry.
- Spawn workers only when a worker can produce independent evidence that the
  judge can verify and integrate cheaply.

### Planning Worker

| Priority | Provider | Model line | Reasoning |
| --- | --- | --- | --- |
| 1 | OpenAI | `terra` latest | `medium` |
| 2 | Anthropic | `sonnet` latest | `medium` |
| 3 | OpenAI | `sol` latest | `high` |
| 4 | Cursor | `composer` | `high` |

Good worker tasks:

- automated test inventory
- affected contract inventory
- migration and rollout constraints
- verification command discovery
- dependency and ownership map

### Technical-Writing Editor

Use the first available entry.

| Priority | Provider | Model line | Reasoning |
| --- | --- | --- | --- |
| 1 | OpenAI | `terra` latest | `medium` |
| 2 | Anthropic | `sonnet` latest | `medium` |
| 3 | OpenAI | `sol` latest | `high` |
| 4 | Cursor | `composer` | `high` |

## Workflow

1. DETERMINE_SCOPE
2. LOAD_CONTEXT
3. DELEGATE_INVESTIGATIONS
4. RESOLVE_DECISIONS
5. PLAN_TESTS
6. DRAFT_PLAN
7. EDIT_TECHNICAL_WRITING
8. CHECK_GATES
9. WRITE_ARTIFACT

### DETERMINE_SCOPE

- Determine the requested change, affected product behavior, planning depth,
  and any plausible nearby work the plan intentionally rejects or defers.
- Name the repository root and planned artifact path:
  `<repository-root>/docs/plans/YYYY-MM-DD_HH:MM_<plan-name>.md`.
- If the request revises an existing plan, use that existing plan path as the
  artifact path.
- Create `docs/plans/` if it does not exist.

### LOAD_CONTEXT

- Use skill: ts-project-context to load shared facts and decisions.
- Read relevant source, tests, docs, configs, `AGENTS.md`, and local guidance.
- Identify current behavior, affected files, invariants, dependencies,
  contracts, test seams, and verification commands.
- Use semantic skill names for external skills, e.g. `skill: ts-principles`.
- Use paths for local files. Do not copy reference material into the plan unless
  the implementer needs the exact snippet.
- If a required read or repo command fails after the obvious fix, stop and
  escalate. Missing context is not a license to plan blindly.

### DELEGATE_INVESTIGATIONS

- Skip when direct planning is cheaper.
- Delegate only independent, bounded fact-finding questions.
- Worker prompts must include the question, exact scope, files or skills to
  read, assigned provider, model line, reasoning level, expected output shape,
  the rule that workers must not write the plan artifact, and the rule that
  workers must escalate tooling failures to the judge instead of silently
  downgrading output.
- Treat worker output as evidence. Deduplicate and reconcile it before
  planning.

### RESOLVE_DECISIONS

- Resolve unknowns from repo and shared project context; retain reusable conclusions in project context.
- Keep unresolved decisions only in `Open Questions`.
- Do not place alternatives inside implementation tasks.
- If a task depends on an unresolved question, mark that task blocked and name
  the dependency.

### PLAN_TESTS

- Re-read the `tests are code` principle detail before planning test changes.
- For each non-trivial behavior change, decide how automated tests will prove it before drafting tasks.
- Each planned test change must name:
  - the behavior or rule it proves
  - the interface or user action it exercises
  - the bug it would catch
- If no tests are added, name the existing automated check or explain why no lasting automated check is practical.

### DRAFT_PLAN

- Write implementation instructions for a skilled engineer with no prior chat
  context. Treat review findings, user feedback, and handoffs as inputs to the
  plan, not content in the plan.
- Use exact file paths, line numbers when useful, and dependency-ordered tasks.
- Make each task leave the repository coherent after its dependencies are
  applied. Do not split a refactor so an earlier task breaks imports, types,
  tests, or runtime behavior that a later task repairs.
- If a task cannot be verified honestly before a dependent task, merge the tasks.
- Put tests in the same task as the behavior change or in a dependent test
  task. For each test task, include the test description from PLAN_TESTS.
- Use exact paths, symbols, commands, and contract names. Explain intent and reasoning in ordinary prose.
- Use `Details` for intent, rules that must remain true, and sequencing. Put exact mechanics in `Code Changes`; do not
  repeat hunks in prose.

Code-in-plan policy:

- Default to diffs. For a small change to a preexisting file, show only the
  changed lines as a patch-style hunk with a few lines of surrounding context.
- Use larger code blocks only for new files, or when extra context is needed to
  understand the change. New files, new functions, new components, new types,
  and heavily rewritten units need full or near-full code.
- Do not dump whole existing files for small edits.
- Do not include generated artifacts, lockfiles, snapshots, or build output
  unless they are the subject of the change.
- Do not hide substantive logic behind `...`.
- Plan `/** ... */` or comments for non-obvious exported contracts, invariants,
  edge cases, error handling, concurrency, performance, security, or domain
  rules.
- Do not plan comments that repeat names, types, schemas, tests, or obvious
  code.

### EDIT_TECHNICAL_WRITING

- Always spawn a technical-writing editor sub-agent after drafting the plan and
  before running gates.
- Include `skill: ts-technical-writing` in the editor prompt.
- The editor owns plan prose, structure, headings, bullets, examples, and
  llm-ism removal.
- The editor edits the plan draft directly. It must return the complete edited
  plan text, not review findings or suggestions.
- The editor must preserve meaning, exact technical names, scope, task order, file paths, code hunks, verification
  commands, open questions, blockers, planned tests, and technical facts. It may rewrite abstract labels and workflow
  terms.
- The editor prompt must name the reader as a skilled engineer with no prior chat context and state that the plan should
  make implementation and verification unambiguous.
- The judge must not perform the technical-writing edit itself. The judge may
  make factual corrections after the edit.
- If factual corrections materially rewrite the plan, run the editor again.

### CHECK_GATES

Before writing the artifact, verify:

- The technical-writing editor edited the plan after the latest material draft
  change.
- The plan stands alone without prior chat.
- Every non-trivial task lists exact files.
- No task asks the implementer to choose between alternatives.
- Every task's `Verify` section is valid immediately after that task and its
  dependencies are applied.
- `Open Questions` contains only unresolved decisions.
- Optional sections marked `skip if none` are omitted when empty.
- No answered question remains as an open question.
- Blocked tasks name their blocker.
- Verification commands and expected results are explicit.
- Every verification command's underlying tool runs in this repo. Invoke each
  tool with a no-op (e.g., `--help`, dry-run, version check, or a no-target
  invocation) to confirm availability. For commands that exercise
  yet-to-be-implemented code, confirming the tool itself is sufficient. If a
  tool cannot run after the obvious fix, escalate.
- Every non-trivial behavior change has a planned automated test, an existing automated check, or an explicit reason no
  lasting automated check is practical.
- Task file lists match the snippets or hunks in that task.
- The plan has no notes about the planning, review, handoff, or revision process.

### WRITE_ARTIFACT

- Write the final plan to the artifact path chosen in `DETERMINE_SCOPE`.
- New plans use `<repository-root>/docs/plans/YYYY-MM-DD_HH:MM_<plan-name>.md`.
- Revisions overwrite the existing plan path. Do not create a revised copy or
  write a delta.
- Use accepted feedback to rewrite the affected sections: summary, overview,
  tasks, planned tests, code changes, verification, open questions, or scope.
- Delete superseded scope instead of describing that it was removed.

## Artifact Template

````markdown
# Plan: <Feature Name>

## Summary
<1-3 sentences describing what this builds and why>

## Prerequisites
<Task-specific setup, dependencies, or docs; skip if none>

## Open Questions
<Unresolved decisions only; skip if none>

## Out of Scope
<Nearby work the reader might reasonably expect from this plan, but this plan rejects or defers; skip if none>

## Overview
<1-2 short paragraphs about architecture, approach, constraints, and sequencing>

## Task <n>: <name>
**Files:** `path/to/file.ts:42`, `path/to/test.ts`
**Depends on:** Task <m>; omit when the task has no dependency
**Blocked by:** <open question or external dependency; omit if unblocked>

**Details:**
- <Intent, rule that must remain true, or sequencing note not obvious from the code>
- <Concrete step only when no code hunk carries it>

**Tests:** <For test tasks only: behavior proved, interface or user action exercised, and bug caught; omit otherwise>

**Code Changes:**
```ts
// Patch-style hunk for small edits; full definition only for new/rewritten code.
```

**Verify:**
- `<command>`
- Expected: <observable result>
````