JetBrains/thinkrail / packages/pi-thinkrail-workflow/skills/writing-specs
writing-specs
VerifiedUse when a workflow step drafts or revises a spec artifact — a goal-and-requirements, an architecture, or a module SPEC — or when a workflow skill names it at such a step. The shared quality bar for specs — not a workflow, nothing to execute.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
SKILL.md
View on GitHub---
name: writing-specs
description: "Use when a workflow step drafts or revises a spec artifact — a goal-and-requirements, an architecture, or a module SPEC — or when a workflow skill names it at such a step. The shared quality bar for specs — not a workflow, nothing to execute."
---
# Writing Specs
The workflow family's shared bar for every spec a workflow produces: **short, honest, on-rails**.
Process skills name this concept at the steps that draft or revise specs; *what* to draft and *when*
stays with the referencing skill. Graph mechanics — frontmatter, link kinds, the `spec_*` tools — are
the spec-graph skill's ground; this concept carries the quality bar the family holds on top of them,
and is where the family's rules for specs and the spec graph accrue.
## Short
- Small enough to read in one sitting. Target signal, not completeness.
- Explain intent, not inventory: what the thing is for, what it owns, where its boundary runs — never
a file listing or a restatement of the code.
## Honest
- Only settled content appears. Never pad with `[TBD]` or placeholder sections — a section that
hasn't been settled simply doesn't exist yet.
- Anything inferred rather than confirmed is marked unconfirmed, inline, where it stands.
- New and inferred specs are `status: draft` until the user has reviewed them — the flip out of
`draft` follows the user's review, never the drafting agent's own judgment. A reviewed durable spec
goes `active`, never `done`: it stays in force and evolves with the project.
## On-rails
- High-signal enough that a future agent (or human) lands on the decisions without re-deriving them.
- The spec is the *only* home for rationale: decisions, invariants, trade-offs, and bug post-mortems
are recorded here, never as code comments — a rationale paragraph found in code is content to
promote into the owning spec, leaving at most a one-line pointer where misediting would silently
break something.
- Say each thing once: link by `id` instead of restating; the dependency edges *between* sibling
modules live in the parent's spec, not in each leaf.
- One spec per *genuine* boundary — not per directory, not per file.
## The goal doc describes the product, not a plan
`goal-and-requirements` is the living record of what the product is and why: its goal, problem,
audience, capabilities, and non-goals, plus any durable principles.
- No versions, releases, phases, MVP/v1/v2 splits, or "later" lists. Sequencing is not a spec's job:
an idea cut from scope goes back to the user to track wherever they plan work, and never into the doc.
- **Capabilities** state what the product does, or for a new project what its smallest useful first
build will do.
- **Non-goals** hold only what is excluded by decision. Something neither listed nor excluded is open,
not forbidden.
- It evolves with the product: a change that adds a capability or overturns a principle updates the goal
doc in the same change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |