realroc/prompt-spec

Prompt Spec

Turn a vague request into an issue an AI agent can execute safely. Or audit an existing prompt and surface what's missing before code gets written.

This skill exists because the real failure mode in AI-native engineering isn't "AI writes wrong code" — it's "human writes incomplete prompt, AI fills the gaps with a plausible-but-disastrous default."

Companion skill: githire (the full six-step workflow). This skill only owns the issue-framing step.

---

The Job

Two modes, picked automatically based on what the user gives you.

Mode A: Audit

Input: an existing prompt / issue / Slack message. Output: which of the 6 sections are missing or weak, and what concrete failure mode each gap maps to.

Mode B: Rewrite

Input: a vague request + enough context to ask follow-up questions. Output: a complete six-section prompt spec the user can paste into an issue or feed to a coding agent.

If the user just pastes a prompt with no instruction, default to Audit and offer Rewrite as the next step.

---

The six sections

| Section | What it answers | Missing → failure mode | |---|---|---| | Goal | What we're trying to achieve, in user-visible terms | AI optimizes for the wrong outcome | | Constraints | Call frequency, data scale, latency budget, schema we can't break | AI picks an implementation that doesn't survive prod load | | Non-goals | What this change must NOT do; concrete anti-patterns | AI happily uses the worst-case implementation that fits the goal | | Verification | Tests, smoke probes, prod metrics that should/shouldn't move | "All tests pass" becomes the only signal; incidents in prod | | Architecture notes | Data structures, index patterns, cache strategy, the shape we expect | AI invents a structure that conflicts with team conventions or prior decisions | | Existing context | Files likely involved, prior decisions, related issues/PRs | AI rebuilds something that already exists or re-introduces an old bug |

---

Mode A · Audit

For each of the six sections, return one of three verdicts:

• ✓ Present — section is there and concrete enough that an AI agent could act on it.
• △ Weak — section is mentioned but vague (e.g., "should be fast" instead of "p99 ≤ 200ms").
• ✗ Missing — section isn't there at all.

Then, for each △ or ✗, name one concrete failure mode that gap enables.

Output format

## Audit · <prompt one-line summary>

| Section | Verdict | Gap → failure mode |
|---|---|---|
| Goal | ✓ / △ / ✗ | (only if △ or ✗) |
| Constraints | ✓ / △ / ✗ | ... |
| Non-goals | ✓ / △ / ✗ | ... |
| Verification | ✓ / △ / ✗ | ... |
| Architecture notes | ✓ / △ / ✗ | ... |
| Existing context | ✓ / △ / ✗ | ... |

### Top risks if shipped as-is
1. <highest-impact gap, what could break, why>
2. <next>
3. <next>

### Suggested next step
- [ ] Fill in <section X> with: <concrete prompt back to the user>
- [ ] Fill in <section Y> with: <concrete prompt back to the user>
- [ ] Once filled, run Mode B (Rewrite) to produce the final spec.

What "weak" looks like (concrete reference)

| Weak phrasing | What's wrong | Stronger version | |---|---|---| | "should be fast" | no number, no percentile | "p99 ≤ 150ms at 50 RPS" | | "use the field" | no shape, no constraint | "read from model_detail.made_in_china; don't introduce new keys" | | "make sure it works" | unmeasurable | "smoke test asserts: cn site returns only made_in_china=1; intl site unchanged" | | "follow best practices" | meaningless | "no SCAN/KEYS in request-path; cache TTL ≥ 60s; reads O(1)" |

---

Mode B · Rewrite

Use this exact template. Fill every section; if a section truly doesn't apply, write N/A — <why>, never leave it blank.

# <One-line title: <verb> <object>>

## Goal
<What we're trying to achieve, in user-visible terms. One paragraph.>

## Constraints
- <Hard limit 1: e.g., `/api/X` is hit on every page load, currently ~200 RPS>
- <Hard limit 2: e.g., model_detail has ~80 entries today, may grow to ~500>
- <Hard limit 3: e.g., must not break the existing /api/Y contract>

## Non-goals
- <Concrete anti-pattern 1: e.g., no SCAN / KEYS / unbounded loops in request-path>
- <Concrete anti-pattern 2: e.g., do not change the frontend caching strategy in this PR>
- <Scope reduction 1: e.g., this PR does not handle <adjacent feature>>

## Verification
- <Test 1: e.g., pytest tests/X — assertion specifically about Y>
- <Smoke 1: e.g., `curl /api/site/config` on cn vs intl, expected diff>
- <Prod metric 1: e.g., `/api/X` p99 must not move > 10ms after rollout>

## Architecture notes
- <Shape 1: e.g., maintain a Redis SET `domestic_model_ids`, write on model up/down>
- <Shape 2: e.g., reads are SMEMBERS — O(1)>
- <Constraint inherited: e.g., per <link to prior PR / ADR>, we standardized on...>

## Existing context
- Likely files: <path1>, <path2>
- Prior related work: <issue/PR/ADR link>
- Known landmines: <e.g., "previous attempt at X is in PR #42, reverted because Y">

---

Real before / after

A real production incident (full walkthrough: https://realroc.github.io/git-hired/case-redis-scan.html) ran with this prompt:

"国产模型判定走的是前缀匹配。我想做成 model_detail 里的 made_in_china 字段。需要针对国内站和国际站分别做 search 检查。建议在 smoke test 那边增加 E2E 测试。"

Audit verdict:

| Section | Verdict | Gap → failure mode | |---|---|---| | Goal | ✓ | — | | Constraints | ✗ | nothing said /api/site/config is hit per page-load → AI used per-request impl | | Non-goals | ✗ | no "no SCAN/KEYS" → AI used r.scan(match='model_detail::*') | | Verification | △ | "smoke test" too vague — didn't say "p99 must not move" → no prod gate | | Architecture notes | ✗ | no mention of maintained set → AI invented a runtime scan | | Existing context | △ | mentioned the field but not "model_detail has ~80 keys, all read-mostly" |

What actually happened: AI generated functionally-correct code in 5 minutes. Production was on fire in 13 hours. 25 hours of fix-chain commits until Redis SET replaced the SCAN.

Rewritten (Mode B output) would have been ~150 words longer and prevented the entire incident. Those 150 words = 25 hours of save.

---

Agent behavior

• Don't write code in this skill. This skill stops at the spec. Handoff to the coding agent (or to githire skill's Execute step) comes after.
• If the prompt is vague AND there's no context to ask from, ask 3–5 lettered clarifying questions (one per truly-missing section, max). Don't ask about sections that are obvious from context.
• If the prompt is short but the surrounding repo / chat history gives enough context, fill the spec yourself and show your assumptions explicitly in each section. Each assumption gets a _<assumption>_ italic note.
• Prefer concrete numbers over adjectives. "Fast" is a smell. Replace with "p99 ≤ Xms".
• Cite the case when a user pushes back on "this is too much for a small change": point at https://realroc.github.io/git-hired/case-redis-scan.html. 150 extra words ≠ 25 extra hours.

---

Clarifying-question format

When asking the user to fill missing sections, use lettered options so the user can answer with 1B, 2A, 3D:

1. What's the call frequency of the entry point you're touching?
   A. One-off / batch job (cold path)
   B. User action (clicks, ~1 RPS per user)
   C. Page-load / startup (high RPS, 10–100×)
   D. Request-path on every API hit (highest scrutiny)

2. What's the data scale today, and 6 months out?
   A. < 100 items, stable
   B. 100–10K items, slow growth
   C. 10K–1M items
   D. > 1M items / unbounded

3. What's the verification bar?
   A. Unit tests only
   B. + smoke / integration
   C. + production metric SLO
   D. + canary / staged rollout

---

Trigger phrases

Activate this skill when the user asks to:

• "audit this prompt" / "check my prompt" / "what's missing in this prompt"
• "rewrite as a prompt spec" / "convert to issue spec" / "frame this as an issue"
• "is this prompt safe to give to AI"
• "spec out this feature" (where the user has a one-liner)

Also activate proactively when:

• The user pastes a short prompt and asks for code → run Audit first, offer Rewrite.
• The user is about to merge an AI-generated PR and the originating issue is < 50 words → audit it.

---

Don't

• Don't pad a prompt that's already complete. If audit returns six ✓ marks, say so and stop.
• Don't add sections beyond the six. The list is intentionally short; new sections fragment the contract.
• Don't fabricate constraints / scale numbers. If you don't have them, ask. Fabricated specs are worse than missing ones.
• Don't write the code in this skill. Stop at the spec; handoff to githire Execute step.