Speclet Spec Skill Skill

Speclet Spec Skill

Convert a draft document into an executable spec.json.

What I Do

Convert .speclet/draft.md into .speclet/spec.json
Create atomic stories with verifiable acceptance criteria
Number functional requirements (FR-1, FR-2, etc.)
Set up passes: true/false tracking for each story

When to Use Me

Use this after creating a draft with speclet-draft skill, or for quick fixes:

Convert draft to executable spec
Create spec-lite for quick fixes (Tier 2)

Your Task

Convert .speclet/draft.md into .speclet/spec.json.

Step 1: Read the Draft

Read .speclet/draft.md and extract:

Feature name and summary
Non-goals
Proposed stories
Files to modify

Step 2: Create spec.json

Generate .speclet/spec.json:

{
  "feature": "[Feature Name]",
  "branch": "feature/branch-name",
  "date": "YYYY-MM-DD",
  "summary": "[1-2 sentences of the goal]",
  "nonGoals": [
    "[What this feature will NOT do]"
  ],
  "functionalRequirements": [
    "FR-1: The system must [specific requirement]",
    "FR-2: When user does X, the system must [response]"
  ],
  "stories": [
    {
      "id": "STORY-1",
      "title": "[Short title - 2-3 words]",
      "description": "[2-3 sentences max]",
      "files": ["path/to/file.ts"],
      "acceptanceCriteria": [
        "[Specific verifiable criterion]",
        "Build/typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Critical Rules

Story Sizing

If you cannot describe the change in 2-3 sentences, it's too big. Split it.

✅ Right-sized:

Add a database column and migration
Add a UI component to an existing page
Update a server action with new logic

❌ Too big (split these):

"Build the entire dashboard"
"Add authentication"

Story Order: Dependencies First

Schema/database changes (migrations)
Server actions / backend logic
UI components that use the backend
Dashboard/summary views

Acceptance Criteria: Must Be Verifiable

✅ Good:

"Add status column with default 'pending'"
"Filter dropdown has options: All, Active, Completed"

❌ Bad:

"Works correctly"
"Good UX"

Always include:

Build/typecheck passes (every story)
Verify in browser (UI stories)

Spec-Lite (Tier 2)

For quick fixes (15-60 min), create .speclet/spec-lite.json:

{
  "feature": "[Title]",
  "branch": "fix/branch-name",
  "date": "YYYY-MM-DD",
  "problem": "[1-2 sentences]",
  "solution": "[Description]",
  "files": ["path/file.ts"],
  "acceptanceCriteria": ["Build passes", "[Criterion]"],
  "passes": false,
  "notes": ""
}

Global Rules

Always Show Recommendation + Reason

When asking questions with options, ALWAYS:

Mark the recommended option with ⭐
Add **Reason for recommendation:** explaining why

Example format:

1. [Question]?
   A. Option A
   B. Option B ⭐ Recommended — [brief reason]
   C. Option C

   **Reason for recommendation:** [Detailed explanation of why B is best]

Output

Full spec: .speclet/spec.json
Quick fix: .speclet/spec-lite.json

When complete:

"Spec saved. Ready to implement? Use the speclet-loop skill."

Agent Skills: Speclet Spec Skill

Skill Files