# Writing Specs

Use when a workflow step drafts or revises a spec artifact, a goal-and-requirements...

- Repository: https://github.com/JetBrains/thinkrail (6952 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add JetBrains/thinkrail --skill writing-specs -g -a claude-code -y`
Codex: `npx skills add JetBrains/thinkrail --skill writing-specs -g -a codex -y`
Cursor: `npx skills add JetBrains/thinkrail --skill writing-specs -g -a cursor -y`
Gemini CLI: `npx skills add JetBrains/thinkrail --skill writing-specs -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/JetBrains/thinkrail/blob/HEAD/packages/pi-thinkrail-workflow/skills/writing-specs/SKILL.md