specre-author

name

specre-author

description

Guidelines for creating new specre cards and editing existing ones. Use this skill when you need to: (1) create a new specre card from scratch, (2) edit an existing specre card (adding scenarios, updating status, filling in sections), (3) verify that a card follows the correct format, naming conventions, and section structure, or (4) understand which sections are required vs. optional. Do NOT use this as the entry point for bulk card generation (use the /specre-generate command instead), or for investigating what a specre card says about existing code (use specre-investigate-intent).

specre Card Authoring Guide

This guide defines how to create and edit specre specification cards. A specre card is a single Markdown file that describes exactly one behavior, with YAML front-matter for lifecycle tracking and bidirectional traceability.

Core Principles

• One file = one behavior. Each specre card describes a single, atomic behavior. If you find yourself writing "also, ..." — split it into a separate card.
• No sequential numbering. Never prefix filenames with 001_, 002_, etc. The ULID in id provides chronological ordering.
• Group with subdirectories. When a domain contains many related behaviors, create subdirectories to organize them. Keep the tree flat where a single level is sufficient.

Where Specre Cards Live

Cards are stored under the directory specified by specre_dir in specre.toml:

<specre_dir>/<domain>/<behavior_name>.md

Example layout:

docs/specres/
  auth/
    signup/
      user_can_sign_up_with_email.md
      system_sends_verification_email_on_signup.md
    password/
      user_can_reset_password.md
  cart/
    user_can_add_item_to_cart.md
    cart_total_reflects_quantity_changes.md

Path Resolution

Before writing Related Files paths, read specre.toml to understand the project layout:

• specre_dir — where specre cards are stored (e.g., docs/specres)
• source_dirs — where implementation and test files live (e.g., ["src", "tests"])

All paths in a specre card's "Related Files" section must be relative to the project root.

Card Format

Front-matter

Every specre card begins with YAML front-matter:

---
id: "01JMXXXXXXXXXXXXXXXXXX"
name: "user_can_sign_up_with_email"
status: "draft"
last_verified: "2026-03-01"
---

Field	Type	Required	Description
id	ULID	Yes	26-character unique identifier, auto-generated by specre new
name	string	Yes	Must match the filename (without .md). Subject + predicate sentence form
status	enum	Yes	draft / in-development / stable / deprecated
last_verified	date	No	YYYY-MM-DD. Required for stable cards. Omit for draft and in-development

Status Lifecycle

draft ──→ in-development ──→ stable ──→ deprecated
  ↑            │                │
  └────────────┘                │
  (requirements changed)        ↓
                           (superseded or removed)

• draft — Behavior is proposed but not yet implemented.
• in-development — Implementation or tests are in progress.
• stable — Implementation matches the specre. Tests pass. Set last_verified to the current date.
• deprecated — Behavior has been removed or superseded. Kept for historical reference.

Sections

Section	Required	Purpose
Related Files	Yes	Paths to source and test files linked to this behavior
Functional Overview	Yes	One-paragraph summary of the behavior
Design Intent	No	Explains why this design was chosen, not what it does
Key Members	No	Important state, parameters, or data structures in natural language
Scenarios	Yes	Step-by-step behavior descriptions for each case
Failures / Exceptions	No	Edge cases and error handling

Naming Conventions

Names must be sentences with a clear subject and predicate that describe the behavior.

Good examples:

• user_can_sign_up_with_email
• system_rejects_expired_token
• cart_total_reflects_quantity_changes
• admin_can_approve_pending_order

Bad examples (function-style nouns — avoid these):

• create_quotation
• password_reset
• token_validation

Writing Guidelines

Write in Natural Language

Scenarios should be written in natural language, not in code. Do not copy-paste implementation details into the specre card.

Exception: Use exact names for signals/events, class names, enum values, and API endpoints — these are the contract between the specification and the code.

Example scenario (good):

### Successful signup

1. User submits a valid email and a password of 8+ characters
2. System creates the account and emits `account_created` event
3. User is redirected to the welcome screen

Example scenario (bad — too implementation-specific):

### Successful signup

1. Call `UserService.create(email, password)` with `bcrypt.hash(password, 12)`
2. Insert into `users` table and publish to `account_created` channel
3. Return `redirect_to(welcome_path)`

Keep Each Card Focused

If a card covers multiple independent behaviors, split it. A card titled user_can_sign_up_and_reset_password should be two separate cards.

Creating and Managing Cards

Create a New Card

specre new <target_dir> --name <behavior_name>

This generates a card with an auto-assigned ULID and template sections.

Link Source Files

Insert a @specre marker in each related source file to create the reverse traceability link:

specre tag <ULID> <source_file_path>

This inserts a comment at line 1 of the source file. The comment syntax is determined by the file extension:

Language	Marker
Ruby / Python / Shell	# @specre 01JMXX...
JavaScript / TypeScript / Rust / Java / C# / C++	// @specre 01JMXX...
HTML / XML	<!-- @specre 01JMXX... -->
CSS	/* @specre 01JMXX... */
SQL	-- @specre 01JMXX...

Regenerate Index

After creating or modifying cards, regenerate the index:

specre index

Check Consistency

specre orphans   # Detect unlinked specre cards and dangling markers
specre status    # Report status counts and flag stale cards

Template

When specre new is not available, use this template to create a card manually:

---
id: "<ULID>"
name: "<behavior_name>"
status: "draft"
---

## Related Files

- `src/<domain>/<file>.<ext>`
- `tests/<domain>/<test_file>.<ext>` (Test)

## Functional Overview

[One-paragraph summary of the behavior]

## Design Intent

[Why this design was chosen]

## Key Members

- `field_name: Type` — description

## Scenarios

### [Scenario name]

1. [Step]
2. [Step]
3. [Step]

## Failures / Exceptions

- [Error case description]