gh-jschulte-claude-plugins-stackshift/skills/convert-to-speckit/SKILL.md

Convert to Spec Kit Format

Skill: convert-to-speckit Purpose: Convert existing docs/reverse-engineering/ documentation into GitHub Spec Kit specifications Use Case: Repository has reverse engineering docs from StackShift Gears 1-2, but needs proper Spec Kit format

---

What This Skill Does

This skill reads your existing reverse engineering documentation and converts it into properly formatted GitHub Spec Kit specifications, ready for the /speckit-* workflow commands.

Prerequisites

Your repository should have:

• docs/reverse-engineering/ directory with documentation files
• .specify/templates/ with Spec Kit templates (will be created if missing)

Process

1. Scan - Read all files in docs/reverse-engineering/
2. Analyze - Identify distinct features and capabilities
3. Extract - Pull out business logic, data models, APIs, integrations
4. Convert - Map to GitHub Spec Kit format
5. Create - Generate specs/F{NNN}-{feature}/spec.md files
6. Validate - Ensure all required sections are complete

---

Step 1: Locate Documentation

I'll scan for reverse engineering documentation:

docs/reverse-engineering/
├── functional-specification.md
├── data-architecture.md
├── api-documentation.md
├── integration-points.md
├── business-logic.md
├── deployment-architecture.md
└── [other analysis files]

Action: Let me read all files in this directory to understand the application.

---

Step 2: Extract Features

From the documentation, I'll identify distinct features. Each feature becomes one specification.

Examples of features:

• User Authentication (login, registration, password reset)
• Product Catalog (listing, search, filtering)
• Shopping Cart (add to cart, update, checkout)
• Payment Processing (cards, validation, receipts)
• Order Management (create, track, update, cancel)
• Admin Dashboard (reporting, analytics, user management)

Question for you: After I list the features I found, you can:

• Confirm priorities (P0 = critical, P1 = important, P2 = enhancement)
• Add features I might have missed
• Skip features not needed right now

---

Step 3: Create Specifications

For each feature, I'll create a properly formatted specification following this structure:

File: specs/F{NNN}-{feature-slug}/spec.md

# Feature Specification: {Feature Name}

**Feature Branch**: `{NNN}-{feature-slug}`
**Created**: {date}
**Status**: Draft
**Priority**: P0 | P1 | P2

## User Scenarios & Testing *(mandatory)*

### User Story 1 - {Capability} (Priority: P0/P1/P2)

As a {user type}, I need {capability} so that {benefit}.

**Why this priority**: {Business value explanation}

**Independent Test**: {How to test this in isolation}

**Acceptance Scenarios**:
1. **Given** {precondition}, **When** {action}, **Then** {outcome}
2. **Given** {precondition}, **When** {action}, **Then** {outcome}
3. **Given** {precondition}, **When** {action}, **Then** {outcome}

---

{3-5 user stories per feature}

---

### Edge Cases

- {5-10 edge cases that need handling}

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST {requirement}
- **FR-002**: System MUST {requirement}
- **FR-003**: System SHOULD {optional requirement}

{10-15 functional requirements}

### Key Entities *(if data-related)*

- **{Entity}**: {Description}

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: {Metric}: {Expected value}
- **SC-002**: {Performance metric}

{8-12 success criteria}

### Non-Functional Requirements

- **Performance**: {Response times, throughput}
- **Reliability**: {Uptime, error rates}
- **Security**: {Auth, encryption, protection}
- **Maintainability**: {Code quality, tests}

## Assumptions

1. {Technical assumptions}
2. {Environment assumptions}
{3-7 assumptions}

## Dependencies

- {External systems, libraries, services}

## Out of Scope

- {Things NOT in this feature}
- {Future enhancements}

## References

- {Documentation links}
- {Standards followed}

---

Conversion Mapping

From Reverse Engineering Docs → Spec Kit

Source	Target
Capabilities, features, "what it does"	User Stories
API endpoints, request/response	Functional Requirements
Database tables, schemas	Key Entities
Business rules, validation	Acceptance Scenarios
Error conditions, limits	Edge Cases
External APIs, services	Dependencies
Tech stack, frameworks	Implementation details (plan.md, not spec.md)

Key Principles

Spec.md describes WHAT, not HOW:

• ✅ "System MUST authenticate users securely"
• ❌ "System MUST use JWT with RS256 algorithm"

Stay technology-agnostic:

• ✅ "System MUST persist data reliably"
• ❌ "System MUST use PostgreSQL with replication"

Focus on outcomes:

• ✅ "System MUST respond within 200ms"
• ❌ "System MUST cache with Redis"

Implementation details go in plan.md, which is created later via /speckit-plan.

---

Quality Validation

Before completing, I'll verify each spec has:

• 3-5 user stories with clear business value
• Each story has 3 acceptance scenarios
• 5-10 edge cases identified
• 10-15 functional requirements (MUST/SHOULD/MAY)
• Key entities listed (if data-related)
• 8-12 measurable success criteria
• Non-functional requirements (performance, security, reliability)
• 3-7 assumptions documented
• Dependencies clearly listed
• Out of scope items specified

---

Example: Before & After

Before (from reverse engineering docs):

API: POST /api/auth/login
- Takes email and password
- Returns JWT token
- Returns 401 if invalid
- Rate limited to 5 attempts

After (Spec Kit format):

### User Story 1 - Secure Login (Priority: P0)

As a registered user, I need to log in with email and password so that I can access my account securely.

**Why this priority**: Core authentication is critical for all user features.

**Independent Test**: Submit valid credentials, verify token returned.

**Acceptance Scenarios**:
1. **Given** valid email and password, **When** login submitted, **Then** authentication token and user profile returned
2. **Given** invalid credentials, **When** login submitted, **Then** 401 error returned without revealing which field failed
3. **Given** 5 failed attempts, **When** login submitted, **Then** 429 rate limit error returned

### Functional Requirements

- **FR-001**: System MUST accept email and password via secure HTTPS
- **FR-002**: System MUST validate email format before auth
- **FR-003**: System MUST return auth token on successful verification
- **FR-004**: System MUST return 401 for invalid credentials
- **FR-005**: System MUST rate limit to prevent brute force (5 attempts)
- **FR-006**: System MUST return 429 when rate limit exceeded

### Success Criteria

- **SC-001**: Login succeeds for valid credentials 99.9% of time
- **SC-002**: Login completes within 500ms at 95th percentile
- **SC-003**: Rate limiting activates after 5 attempts per 15 minutes

---

Ready to Convert!

I'm ready to help convert your reverse engineering docs to Spec Kit format.

What I need from you:

1. Confirm: Do you have docs/reverse-engineering/ with documentation?
2. Preferences: Any specific features to prioritize or skip?
3. Review: After I list features found, confirm priorities (P0/P1/P2)

What I'll deliver:

1. Analysis of all features found
2. Priority recommendations
3. Complete spec files in specs/F{NNN}-{feature}/spec.md format
4. Summary table of what was created

Next steps after conversion:

1. Review specs: Check they capture all requirements
2. Run /speckit-plan on each spec to create implementation plans
3. Run /speckit-tasks to generate actionable task lists
4. Run /speckit-implement to execute the implementation

---

Let's begin!

I'll start by reading your docs/reverse-engineering/ directory. Please confirm you're ready, and I'll begin the conversion process.