pythia-spec

Original：🇺🇸 English

Translated

Use when the developer asks to build or change something and the request leaves real decisions open - a new feature or flow ("build X", "lam luong Y", "them chuc nang Z"), a behaviour with more than one reasonable shape, a security or audit trade-off, or scope that could be read two ways. The request arrives as plain words, not a command - this skill fires on the words. Surface those decisions as questions with options and trade-offs, get them settled, and only then move to impact and write. Also use the moment you catch yourself choosing a business behaviour mid-implementation that the developer never stated.

5installs

Sourcethaildhe172591/pythia

Added on2026-08-27

NPX Install

npx skill4agent add thaildhe172591/pythia pythia-spec

SKILL.md Content

View Translation Comparison →

Settling the Spec

Announce at start: "Using pythia-spec — this request has open decisions that are yours, not mine."

Phase: Learn → Ask — learn enough to ask well, ask until the spec is settled, and only then build

The other skills are the construction chain: they start after the spec is settled. This skill owns the moment before — because an agent that quietly settles the spec itself will build the wrong thing fluently, and the developer's first chance to disagree arrives after the code exists, when every choice costs a rewrite.

The Iron Law

SPEC DECISIONS BELONG TO THE DEVELOPER. YOU PROPOSE; THEY CHOOSE.

Spec or technical? The line that decides who decides

Spec — ask first	Technical — decide yourself, cite your source
What is stored: new table vs new columns, what is kept vs deleted	Names and shapes — the conventions already decide them
Business behaviour: expiry times, retry limits, lockout counts, who is allowed	Which dictionary view or query answers a question
Security ↔ audit trade-offs: delete the token vs keep the trail	Following an existing pattern found via `similar`
Channels and scope: email or SMS, which tenants, which callers	Datatype dictated by the house rules for that kind of value
Deviating from a mandatory convention	Anything `pythia conventions` or the codebase answers

Rule of thumb: if two senior developers could reasonably ship different behaviour, it is spec. If the codebase or the conventions already answer it, it is technical — decide, and show the căn cứ.

The Workflow

Learn enough to ask well — not enough to start building.
```
cols
```
and
```
src
```
on the tables involved,
```
conventions
```
,
```
similar
```
for how this house solves it. The output of this step is better questions, not code.
List every decision you would otherwise settle silently. The test: walk your imagined implementation and note each point where you picked a behaviour the developer never stated.
Ask, one at a time, options with trade-offs and a recommendation — never an open "what do you want?". Each option says what it costs: "OTP over SMS: 6 digits is guessable, so it forces an attempt counter and a lockout column — different table than the draft."
Write the settled spec back in a few lines and get a nod. That paragraph is now the scope —
```
pythia-write
```
's "the developer's sentence". This summary is not skippable; it is what was agreed.
Offer the written artifacts — the developer chooses. "Spec settled. Want it as a spec file and a step-by-step plan first, or build now?" Skipping is a legitimate answer; record it in one line and move on. The questions were the mandatory part — the documents never are.
Hand off: impact → write → apply, as always.

Caught deciding mid-build?

Stop at that line. A new open decision discovered while coding is a new question — asking it late is cheap; presenting it as a fait accompli in the final report ("I also decided...") is the exact failure this skill exists to prevent.

Red Flags — STOP if you catch yourself thinking

Thought	Reality
"The task is simple, asking would stall"	Simple requests hide the most spec: a forgot-password flow carries seven of them. Three questions cost a minute; unbuilding costs an afternoon.
"Lazy mode says don't stall on questions"	Lazy shortens the solution, never the understanding. Settling spec IS understanding.
"I'll flag my choices in the final report"	By then the developer can only agree or demand rework. That is not a choice, it is a bill.
"A brainstorming skill from another pack will handle it"	If one fired, follow it. If none did, this is the floor — the kit assumes nothing else is installed.
"The developer said 'just do it'"	That covers the decisions they could see. New ones you discover are still theirs.
"They skipped the spec file, so I can skip the questions"	Backwards. The questions are mandatory; only the documents are optional.

When NOT to use this skill

The request is fully specified, or a bug with one defensible correct behaviour — go straight to
```
pythia-impact
```
.
The developer already answered — do not re-ask what is settled; re-ask only what changed.
Pure refactors that keep behaviour identical.