functional-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Functional Specification Skill

Use this skill when the user wants a Functional Specification, product requirements document, or other outcome-focused spec that should remain valid even if the implementation changes.

## Core principle

Write the destination, not the journey.

- Describe what must be true for users, operators, or external systems.
- Describe observable behavior, policies, constraints, and acceptance criteria.
- Avoid locking the document to architecture, code structure, vendors, or execution plans unless those details are part of the external contract.

The spec should still read as correct if the team later changes the tech stack, data model, service boundaries, UI framework, or rollout approach.

## What a good Functional Specification contains

- Problem statement
- Goals and intended outcomes
- Scope and non-goals
- Actors or user types
- Functional requirements
- Business rules and invariants
- User-visible states and transitions
- Inputs, outputs, and externally visible interfaces
- Edge cases and failure behavior from the user's perspective
- Acceptance criteria
- Assumptions, dependencies, and open questions

## What to avoid

Do not include these unless they are externally binding requirements:

- Internal architecture
- Database tables or schemas
- Queues, cron jobs, workers, or event buses
- Class names, hooks, services, modules, or file structure
- Endpoints or RPC method names that are not part of a published contract
- Step-by-step implementation plans
- Team task breakdowns, milestones, or rollout phases
- Test implementation details
- Monitoring or instrumentation mechanics
- One specific technical approach presented as if it were the requirement

If a detail could change without changing the promised behavior, it probably does not belong in the Functional Specification.

## Durable writing test

Before keeping any sentence, ask:

1. Would this still be true if the implementation were rewritten from scratch?
2. Is this observable by a user, operator, admin, partner, or external system?
3. Is this a requirement, or just one possible solution?

If the sentence fails that test, rewrite or remove it.

## Rewrite implementation details into functional statements

Translate brittle wording into durable wording.

- Instead of: "Use Redis to enforce rate limits."
- Write: "Requests beyond the allowed threshold are blocked consistently across all application instances."

- Instead of: "Create a retry queue for failed sync jobs."
- Write: "Transient synchronization failures are retried automatically before the user is asked to act again."

- Instead of: "Store audit rows in Postgres."
- Write: "Authorized administrators can review a complete history of relevant changes."

- Instead of: "Add a webhook to notify downstream systems."
- Write: "Connected external systems are notified when the status changes within the required time window."

- Instead of: "Call `/v2/refunds` and set `refund_state=pending`."
- Write: "Authorized support staff can initiate a refund, and the refund is shown to the customer as pending until it is finalized."

## Clarify only what matters

Ask short questions only when the destination is underspecified. Prioritize questions like:

- Who is the actor?
- What must they be able to do, see, or prevent?
- What must always be true?
- What is explicitly out of scope?
- How will we know the requirement is satisfied?
- Are there external contracts, regulatory rules, or hard deadlines that are part of the requirement?

If exact values are unknown, do not invent them. Mark them as open questions.

## Writing rules

- Prefer "must" for required behavior and "must not" for prohibited behavior.
- Make each requirement independently testable.
- Use stable domain language, not temporary project code names.
- Separate policy from implementation.
- State thresholds, limits, and timing expectations explicitly when they matter.
- Describe failures in terms of what the actor experiences and what the system guarantees.
- Keep requirements atomic. Split compound requirements into smaller numbered items.
- Use examples only to illustrate behavior, not to narrow the requirement accidentally.

## Recommended structure

Use this structure unless the user asks for a different format.

```markdown
# <Feature or capability name>

## Summary

<One short paragraph describing the outcome this feature must deliver.>

## Problem

<What problem exists today and who it affects.>

## Goals

- <Desired outcome>
- <Desired outcome>

## Non-Goals

From skuridin/agent-stuff, Apache-2.0.

More from skuridin/agent-stuff