Spec Author

Spec Author Skill

Purpose

Transform raw, incomplete, or ambiguous product ideas into structured, implementation-ready specifications. A good spec eliminates the guesswork from engineering, surfaces hidden constraints before coding begins, and creates a shared contract between product, design, and engineering.

This skill operates across five sequential phases: Why → Scope → Technical → Draft → File.

Do not skip phases. Do not generate a spec from the first message alone. The quality of the output depends entirely on the discipline of the process.

---

Trigger Conditions

Invoke this skill when the user says any of the following (or close variants):

• "spec this out"
• "write a spec for…"
• "turn this into a ticket"
• "make this a GitHub issue"
• "file a backlog item"
• "write up a technical requirement"
• "I have an idea, help me think it through"
• "what do we need to build for…"
• "write implementation-ready docs for…"
• "draft a feature proposal"
• "write acceptance criteria for…"

---

Core Principles

1. Intent over literal request. What the user said is often different from what they meant. Your job is to surface the difference before writing a single word of spec.
2. Read before you write. Never author a technical spec without first reading the relevant code. Specs that ignore existing implementation details are fiction, not engineering.
3. Quality is a gate, not a goal. A spec that scores below 7/10 on the internal quality rubric must not be filed or handed to engineering. Revise until it passes.
4. Scope is sacred. Every spec must have an explicit "Out of Scope" section. Undefined boundaries are debt accrued before a line of code is written.
5. Acceptance criteria are testable, not descriptive. "The page should look good" is not an acceptance criterion. "The page renders within 200ms at P95 under 100 concurrent users" is.

---

Phase 1: Why (Intent Extraction)

Goal: Understand the real problem being solved before anything is designed or scoped.

Steps

1. Read the user's input carefully. Identify:

• What they explicitly stated (the surface request)
• What problem they are actually trying to solve (the root need)
• Who is affected (the user persona or system actor)
• What "done" looks like to them intuitively

1. Ask clarifying questions if the intent is unclear. Ask at most three questions at once. Do not overwhelm with a questionnaire. Prioritize the highest-leverage unknowns:

• "What outcome does this enable that isn't possible today?"
• "Who is the primary user of this feature, and what is their job-to-be-done?"
• "Is there a specific failure mode or pain point driving this request?"

1. Write a Problem Statement (2–4 sentences). This must:

• Name the actor(s)
• Describe the gap or pain
• Explain why solving it matters now
• Avoid naming any solution

1. Validate the problem statement with the user before proceeding. If they correct it, revise and revalidate.

What the User Said vs. What They Meant

This is the most important judgment you make in Phase 1. Examples:

| What they said | What they likely meant | |---|---| | "Add a dark mode toggle" | Users are complaining about eye strain; the visual experience needs to adapt to system preferences | | "Fix the login bug" | Authentication is flaky and users are getting logged out unexpectedly, causing churn | | "Make the dashboard faster" | The dashboard loads slowly on mobile and users abandon before it finishes | | "Add an export button" | Users need to move data out of the system into Excel for reporting workflows | | "Refactor the auth module" | The auth code is hard to extend, and a new SSO requirement is blocked behind it |

Never accept the surface request as the full truth. Dig one level deeper in every case.

---

Phase 2: Scope (Boundary Definition)

Goal: Establish exactly what is and is not part of this unit of work.

Steps

1. Based on the validated problem statement, draft an initial feature boundary. Be specific and opinionated. Vague scope boundaries are the primary source of scope creep.

1. Enumerate what is explicitly included:

• User-facing behaviors
• System behaviors
• Data changes (schema, state, storage)
• API changes (new endpoints, modified contracts)
• Configuration or environment changes

1. Enumerate what is explicitly excluded (Out of Scope):

• Adjacent features the user might assume are included
• Future phases intentionally deferred
• Edge cases that are acknowledged but not addressed in this iteration
• Platform or environment constraints (e.g., "mobile-only, no desktop in this phase")

1. Identify dependencies:

• Other systems, services, or teams that must be involved
• Prerequisites that must be completed first
• Shared infrastructure this feature relies on

1. Estimate effort tier (not story points — use t-shirt sizing):

• XS: 2 weeks, multi-sprint, should be decomposed before filing

If the estimate is L or XL, recommend decomposition before continuing. Offer to help break it down.

1. Confirm scope with the user. Do not proceed to Phase 3 until the boundary is agreed.

---

Phase 3: Technical (Code Reading & Constraint Discovery)

Goal: Ground the spec in actual implementation reality. Surface constraints, risks, and existing patterns before writing any requirements.

Mandatory Steps

> This phase requires reading code. Do not skip it. Specs written without reading the codebase produce incorrect assumptions that waste engineering time.

1. Locate relevant files. Based on the scope, identify:

• Entry points (routes, controllers, handlers, main modules)
• Data models (schema definitions, ORM models, type definitions)
• Existing utilities or abstractions the feature should reuse
• Test files that describe current behavior

Use Bash, Read, Search, and List tools to explore. Do not guess at file paths.

1. Read the relevant code. For each relevant file:

• Understand the current data flow
• Identify existing patterns the new feature must follow (naming conventions, error handling style, logging patterns)
• Note any hardcoded assumptions that may conflict with the new requirement
• Identify tech debt that intersects with the proposed change

1. Document technical constraints. Record:

• Schema constraints (foreign keys, nullable fields, index requirements)
• API contract constraints (versioning, backward compatibility)
• Framework or library constraints (ORM limitations, router restrictions)
• Performance constraints (query budget, latency SLAs)
• Security constraints (auth requirements, input validation rules, PII handling)
• Platform constraints (browser support, OS targets, runtime environment)

1. Identify implementation risks. Flag anything that:

• Requires migration of existing data
• Touches shared infrastructure with blast radius beyond this feature
• Introduces a breaking change to existing API consumers
• Has no existing test coverage that would catch regressions

1. Map existing tests. Note what is already covered and where new tests are required.

1. Summarize findings. Write a concise Technical Context block (see template below) before drafting requirements.

---

Phase 4: Draft (Specification Writing)

Goal: Produce a complete, structured specification document that a developer can implement from without asking clarifying questions.

Spec Template

Use this exact structure for every spec produced by this skill:

# [Feature / Bug Title] — Spec

**Status:** Draft | Review | Approved  
**Author:** [name or "spec-author skill"]  
**Date:** YYYY-MM-DD  
**Effort:** XS | S | M | L | XL  
**Priority:** P0 (critical) | P1 (high) | P2 (medium) | P3 (low)  
**Labels:** [comma-separated tags, e.g., backend, auth, mobile, breaking-change]

---

## 1. Problem Statement

> [2–4 sentences. Name the actor, describe the gap, explain why it matters now. No solution language.]

---

## 2. Goal

> [One sentence. What the system or user can do after this is shipped that they cannot do today.]

---

## 3. Background & Context

> [Optional. Any historical context, prior attempts, related issues, or external requirements (customer request, compliance mandate, OEM spec, etc.) that inform this work.]

---

## 4. User Stories

Format: **As a [actor], I want to [action] so that [outcome].**

- As a [role], I want to [behavior] so that [value].
- As a [role], I want to [behavior] so that [value].
- (Add as many as needed to cover the full user-facing surface of the feature.)

---

## 5. Functional Requirements

Requirements must be:
- Written in imperative form ("The system SHALL…" or "The API MUST…")
- Uniquely numbered (REQ-001, REQ-002, …)
- Testable — each one maps to at least one acceptance criterion

### 5.1 Core Requirements (Must Have)

- **REQ-001:** [Requirement statement]
- **REQ-002:** [Requirement statement]

### 5.2 Secondary Requirements (Should Have)

- **REQ-010:** [Requirement statement]

### 5.3 Future / Deferred (Won't Have — This Iteration)

- **REQ-020 (deferred):** [Requirement statement — noted for future phases]

---

## 6. Technical Context

> [Populated in Phase 3. Describe relevant existing code, patterns, and infrastructure.]

### 6.1 Affected Files / Modules

| File / Module | Role | Change Type |
|---|---|---|
| `path/to/file.ext` | [what it does] | Modify / Create / Delete |

### 6.2 Data Model Changes

```sql
-- Example: new columns or tables
ALTER TABLE users ADD COLUMN theme VARCHAR(10) DEFAULT 'light';

> If no schema changes: "None required."

6.3 API Changes

| Method | Path | Change | Notes | |---|---|---|---| | GET | /api/v1/users | Add theme field to response | Backward-compatible |

> If no API changes: "None required."

6.4 Technical Constraints

• [Constraint 1 — e.g., Must remain backward-compatible with API v1 consumers]
• [Constraint 2 — e.g., Cannot exceed 50ms added latency to auth middleware]
• [Constraint 3 — e.g., PII fields must not appear in application logs]

6.5 Implementation Risks

| Risk | Severity | Mitigation | |---|---|---| | [Description] | High / Medium / Low | [Mitigation strategy] |

---

7. Acceptance Criteria

Acceptance criteria must be:

• Specific: Reference exact values, states, or behaviors
• Testable: A QA engineer or automated test can verify pass/fail without ambiguity
• Atomic: One observable outcome per criterion
• Numbered: AC-001, AC-002, …

Format: Given [precondition], when [action], then [observable outcome].

• AC-001: Given a user with role = admin, when they navigate to /settings, then the theme toggle is visible and defaults to the user's saved preference.
• AC-002: Given a user toggles dark mode, when the page reloads, then the dark mode preference persists across sessions.
• AC-003: Given the theme API endpoint is called with an invalid value, then the system returns HTTP 422 with error code INVALID_THEME_VALUE.
• AC-004: Given the feature flag dark_mode_enabled is false, then the toggle is hidden and no theme classes are applied.

---

8. Out of Scope

The following are explicitly not part of this spec:

• [Item 1 — e.g., Custom user-defined color themes (deferred to v2)]
• [Item 2 — e.g., Dark mode support on the mobile app (separate ticket required)]
• [Item 3 — e.g., Automatic theme switching based on time of day]

> Anything not listed in Sections 5 or 7 is out of scope by default. If in doubt, it's out of scope.

---

9. Security & Privacy Considerations

• [ ] Does this feature handle PII? If yes, describe storage, access, and retention policy.
• [ ] Does this feature expose a new API surface? If yes, describe authentication and authorization model.
• [ ] Does this feature change access control logic? If yes, describe the change and risk.
• [ ] Does this feature introduce new third-party dependencies? If yes, list and assess.
• [ ] Does this feature log user behavior? If yes, ensure compliance with applicable privacy policies.

---

10. Test Plan

Unit Tests

• [What logic needs unit coverage and in which file/module]

Integration Tests

• [What API contracts or service interactions need integration coverage]

End-to-End Tests

• [What user journeys must be covered in automated E2E or manual QA]

Regression Risks

• [What existing behavior could be broken by this change and how to verify it is not]

---

11. Definition of Done

• [ ] All functional requirements (Section 5.1) are implemented
• [ ] All acceptance criteria (Section 7) pass in staging
• [ ] Unit tests written and passing (minimum threshold: 80% line coverage on new code)
• [ ] Integration tests written and passing
• [ ] No new MISRA / CERT / linting violations introduced
• [ ] Code reviewed and approved by at least one peer
• [ ] Documentation updated (API docs, README, changelog, or runbook as applicable)
• [ ] Feature flag (if applicable) tested in both on/off states
• [ ] Security considerations checklist (Section 9) completed and signed off
• [ ] Spec status updated to Approved and filed in team corpus
• [ ] Linked to parent epic or milestone (if applicable)
• [ ] Shipped via /ship workflow and source issue closed on merge

---

12. Open Questions

> Questions that remain unresolved at the time of filing. Each must have an owner and a target resolution date.

| # | Question | Owner | Due | |---|---|---|---| | 1 | [Question] | [Name / Team] | YYYY-MM-DD |

---

13. References

• [Link to related issue, PR, design file, architecture doc, or customer feedback]
• [Link to relevant code or documentation]
• [Link to standard or compliance requirement, e.g., ISO 26262 ASIL level]

---

## Phase 5: File (Archiving & Integration)

**Goal:** Save the spec to the team corpus, link it to the ship workflow, and ensure it is discoverable for future work.

### Steps

1. **Save the spec file.** Write the spec to:
   ```
   .specs/-.md
   ```
   Where `` is a kebab-case summary of the feature title (e.g., `2025-07-22-dark-mode-toggle.md`).

   Create the `.specs/` directory if it does not exist.

2. **Create the `.specs/index.md` registry** (or append to it if it exists). Each entry:
   ```markdown
   - [Dark Mode Toggle](.specs/2025-07-22-dark-mode-toggle.md) — 2025-07-22 — Status: Draft — P1 — M
   ```

3. **Commit the spec** (if in a git repo):
   ```bash
   git add .specs/
   git commit -m "spec: add dark-mode-toggle spec (P1, M effort)"
   ```
   Include `Generated with BEACON` in the commit body per repo convention.

4. **File as GitHub issue** (if the user requests it):
   - Title: `[Spec] Feature Title — Priority | Effort`
   - Body: the full spec markdown
   - Labels: derived from the spec's Labels field
   - Milestone: link to current sprint or roadmap milestone if known

5. **Link to ship workflow.** Inform the user:
   > "This spec is ready for implementation. When the work is complete, use `/ship` to open a PR. The `/ship` workflow will close this issue automatically on merge if you reference it with `Closes #` in the PR description."

---

## Quality Gate

**Every spec produced by this skill must be scored before it is delivered.**

Score the spec on the following rubric. Each criterion is worth 1 point:

| # | Criterion | Pass Condition |
|---|---|---|
| 1 | Problem Statement | Present, actor-named, no solution language |
| 2 | Goal | One sentence, measurable outcome |
| 3 | User Stories | At least one story per user-facing behavior |
| 4 | Requirements | Imperatively written, numbered, traceable to ACs |
| 5 | Technical Context | Real code read; files, constraints, risks documented |
| 6 | Acceptance Criteria | Given/When/Then format, specific values, numbered |
| 7 | Out of Scope | At least two explicit exclusions |
| 8 | Security Checklist | All f

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [CODE-SAURABH](https://github.com/CODE-SAURABH)
- **Source:** [CODE-SAURABH/OpenSkills](https://github.com/CODE-SAURABH/OpenSkills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.