spec-to-comms

Files (1)

• SKILL.md

SKILL.md (first lines)

# Create a Developer Communication from a Blueprint

Read the feature's design document and write a human-facing overview document at
`docs/features/{feature}/overview.md`. The overview translates the design's implementation
detail into what impacted engineers need to know: why the change is happening, what is
moving, and what their code will look like after.

**Source document:** the feature's `blueprint.md` (or, for older features, `tech-spec.md`).
"The spec" throughout this skill means whichever of these exists.

## Environment

| | Claude Code | Claude chat |
|---|---|---|
| **Reading the spec** | Read from `docs/features/{feature}/blueprint.md` (or the legacy `tech-spec.md`) | Ask the user to paste the design doc |
| **Writing the overview** | Write to `docs/features/{feature}/overview.md` | Produce as markdown artifact; tell user the intended path |
| **Supporting docs** | Read any analysis docs in the same `docs/features/{feature}/` directory | Ask the user to paste relevant summaries |

If Read, Write, and Edit tools are available in your toolset, you are in Claude Code; otherwise
you are in Claude chat.

## Before writing

Read the design document. Also read any supporting analysis documents in the same directory (e.g.,
dependency analysis, spike outputs). These often contain findings that clarify domain
boundaries or constraints that are relevant to impacted developers.

Identify the audience: developers whose code will be changed by this work. They are not the
implementers. They need to understand the impact on their service, not how the migration tool
works.

Ask the user one question before drafting if the answer is not clear from the spec:

- Does this change require the reader to take any manual action, or is their code migrated
  automatically?

If the spec makes this clear (e.g., "a migration tool rewrites all consumers atomically"),
skip the question and proceed.

## What to include

**Lead with why and what.** Structure the overview with a `### Why` and `### What` subsection
under the top-level `## Overview`. The Why explains the technical or business problem being
solved (cache invalidation, build times, blast radius, etc.). The What states what is
happening at a high level.

**What's changing and when.** A concise numbered list of phases from the consumer's
perspective. Each phase entry names what moves and what that means for the reader. Skip
internal implementation details (tool names, algorithm choices, PR sequencing steps).

**What changes in your code.** For any phase that changes import paths, type qualifiers, or
mock usage, include concrete before/after code examples. Examples should be copy-paste-ready
and use the actual import paths from the spec. If multiple domains are involved, show a
multi-domain example.

**Domain boundary lists.** Show which types or interfaces move to which packages as bullet
lists, not tables. Single-column tables do not paste well into Notion and other tools. Use a
bold label with a colon for the package name and description, followed by a bullet list of
type names. Collapse file-level detail into type-level summaries; the audience cares about
type names, not source files.

**Migration order.** If the spec defines a migration order (e.g., hottest domain first),
include it. Developers need to know when their service will be affected.

**Backward compatibility (or lack thereof).** If the spec explicitly states there are no
re-exports or compatibility shims, call this out clearly as a prominent paragraph. Developers
mid-PR during a domain migration need to know their imports will be rewritten atomically.

## What to omit

Leave out anything that is only relevant to the people doing the migration:

- How the migration is implemented (tool internals, algorithm choices, invocation steps)
- Internal PR sequencing steps that have no consumer-visible effect
- Test infrastructure details (harness mechanics, generated file movement, test helper changes)
- Open questions that are blockers for implementers but not for consumers
- Design decisions that are TBD for later phases and have no current consumer impact

Examples of things to omit: migration tool location and dependencies, symbol map structure,
`go:generate` directive details, SCC/cycle-detection mechanics, `analysistest` harness usage.

If the spec has an Open Questions section, omit it entirely. Consumers do not act on
unresolved implementation questions.

## Style rules

- Use plain prose. No em dashes (`--` or Unicode em dash). Use a single hyphen (`-`), a
  semicolon (`;`), or parentheses where an em dash would appear.
- A table with only one column is never a table. Use a bullet list instead.
- Headers use title-style separators with a single hyphen, e.g. `## Phase 1 - Interface Split`.
- Bold labels followed by descriptions use a colon, e.g. `**Interface imports:** the qualifier
  changes...`.
- List items that are label-description pairs use a colon separator, not a dash.
- Keep sentences short. The reader is skimming to understand impact, not reading a design doc.
- Do not add comments to code examples.

## Document structure

Use this skeleton; drop sections that do not apply, add sections the spec demands:

```markdown
# {Feature or Change Name}

## Overview

{One paragraph summary of the package or system being changed.}

### Why

{Why this change is happening: the technical or business problem it solves.}

### What

{What is being done at a high level, and that it is phased.}

## What's Changing and When

{Numbered list of phases from the consumer's perspective.}

From thrawn01/claude-dotfiles, MIT.

More from thrawn01/claude-dotfiles