michsindlinger/specwright/templates/skills/architect-refinement

Architect Refinement Skill

Project: [PROJECT_NAME] Generated: [DATE] Purpose: Guide for technical refinement of user stories

When to Use

This skill guides you when doing technical refinement for:

• New stories in /create-spec
• Added stories in /add-story
• Quick tasks in /add-todo
• Bug stories in /add-bug

---

Story Format (Canonical — Single Source of Truth)

The canonical story format is defined in specwright/templates/docs/story-template.md (Fallback: ~/.specwright/templates/docs/story-template.md).

This template is binding. Do not improvise story structure.

This skill provides methodology (how to think about WAS/WIE/WO, when a story is READY, how to classify layers) and project-specific architecture guidance. It does not define the story file layout — the template does.

When creating or refining stories:

1. Load story-template.md first → use its section structure (headings, field names, ordering).
2. Fill the template's **WAS:**, **WIE:**, **WO:** fields using the methodology from this skill.
3. Use project-specific architecture standards below for WIE/WO content.

The conceptual sections below (### WAS, ### WIE, ### WO) are this skill's own structure for teaching the methodology — they are not a story-format prescription.

---

Quick Reference

Technical Refinement Process

1. Understand Requirements: Read fachliche story (Feature, Acceptance Criteria)
2. Analyze Architecture: What patterns apply?
3. Determine WAS: Which components to create/modify
4. Determine WIE: Architecture guidance and constraints
5. Determine WO: Which files to touch
6. Define DoD: Completion criteria
7. Mark DoR: All checkboxes [x] when ready

Story is READY when

• [ ] Fachliche requirements clear
• [ ] Acceptance criteria specific and testable
• [ ] Technical approach defined (WAS/WIE/WO)
• [ ] Dependencies identified
• [ ] Story appropriately sized (max 5 files, 400 LOC)
• [ ] All betroffene Layer identified (Frontend/Backend/Database)
• [ ] Integration points documented (if Full-stack)

---

Detailed Guidance

WAS (What to Build)

Components/Features to create or modify - NO CODE

Examples:

• "User registration service"
• "Profile edit form component"
• "Email validation middleware"
• "User database migration"

Anti-patterns:

❌ "Add function validateEmail()"  // Too specific
✅ "Email validation logic"

❌ "Create UserController with create(), update() methods"  // Implementation details
✅ "User API endpoints"

WIE (How/Architecture Guidance)

Patterns and constraints - NO IMPLEMENTATION

Examples:

• "Use Service Object pattern"
• "Follow existing UserController pattern"
• "No direct DB calls from controllers"
• "Requires rate limiting"
• "Use caching for performance"

Anti-patterns:

❌ "def create_user(params)..."  // Code implementation
✅ "Use Service Object pattern for business logic"

❌ "Add try-catch in line 45"  // Too specific
✅ "Implement error handling with custom exceptions"

WO (Where/Files)

File paths to create or modify - NO CONTENT

Examples:

• "app/services/users/register.rb"
• "src/app/components/user-profile/"
• "db/migrate/[timestamp]_add_email_to_users.rb"

Guidelines:

• List all files that will be touched
• Include new files to create
• Include existing files to modify
• Be specific with paths

Domain Reference (v3.0)

NEW in v3.0: Stories can reference domain areas

**Domain:** user-registration

This tells the main agent:

• Which business process this affects
• Which domain doc to keep updated
• Business context to consider

Layer Analysis

Identify all affected layers:

| Layer | Components | What Changes | |-------|------------|--------------| | Frontend | ProfileForm, Avatar component | New edit form, image upload | | Backend | UserService, ProfileController | Update endpoint, validation | | Database | users table | Add avatar_url column | | DevOps | - | No changes |

Integration Type:

• Backend-only
• Frontend-only
• Full-stack

Critical Integration Points (if Full-stack):

• Backend API Response → Frontend Component
• Database Schema → Backend Query
• Frontend Form → Backend Validation

DoD (Definition of Done)

Start all items unchecked [ ]

Standard DoD items:

#### Implementierung
- [ ] Code implemented and follows style guide
- [ ] Architecture patterns followed (WIE section)
- [ ] Security/performance requirements met

#### Qualitätssicherung
- [ ] All acceptance criteria satisfied
- [ ] Unit tests written and passing
- [ ] Integration tests written (if applicable)
- [ ] Linter passes

#### Dokumentation
- [ ] Code is self-documenting or has comments
- [ ] No debug code left in

Add story-specific items based on requirements.

Completion Check Commands

Provide bash commands to verify story completion:

# File existence
test -f src/app/components/profile/edit.component.ts && echo "Component OK"

# Content verification
grep -q "export class ProfileEditComponent" src/app/components/profile/edit.component.ts && echo "Class OK"

# Tests pass
npm test -- profile.component.spec.ts

# Linter
npm run lint

All commands must exit with code 0 for story to be DONE.

---

Architecture Patterns Reference

Common Patterns by Layer

Frontend:

• Smart vs Dumb Components
• Container/Presenter
• State Management (Context, Store, Signals)
• Form Validation

Backend:

• Service Objects
• Repository Pattern
• Controller → Service → Repository
• Result/Either Pattern

API:

• RESTful endpoints
• Request/Response DTOs
• Error handling
• Pagination

Database:

• Migration for schema changes
• Validations in model
• Scopes for queries
• Associations

Security Checklist

• [ ] Input validation
• [ ] SQL injection prevention
• [ ] XSS prevention
• [ ] CSRF protection
• [ ] Authentication required?
• [ ] Authorization rules defined?

Performance Checklist

• [ ] N+1 queries avoided
• [ ] Large datasets paginated
• [ ] Caching considered
• [ ] Eager loading for associations
• [ ] Indexes on foreign keys

---

Story Sizing Guidelines

Maximum Limits

• Files: Max 5 files per story
• LOC: Max 400 lines of code
• Complexity: Max S (Small, 1-3 SP)
• Concerns: Single concern per story

When to Split

Split story if:

• More than 5 files affected
• Multiple unrelated changes
• Can be done independently
• Different developers could work on parts

---

Dependencies Analysis

Types of Dependencies

Hard Dependency (Sequential):

Story A → Story B
Example: "User model" before "User registration"

Soft Dependency (Optional):

Story A ⇢ Story B (better if A done first)
Example: "Basic search" before "Advanced filters"

No Dependency (Parallel):

Story A ∥ Story B
Example: "Profile edit" and "Avatar upload" can be parallel

How to Document

**Abhängigkeiten:** STORY-001, STORY-003

Or if none:

**Abhängigkeiten:** None

---

v3.0 Changes

What's Different

REMOVED in v3.0:

• ❌ No "WER" (Agent) field
• ❌ No "Relevante Skills" section
• ❌ No skill-index.md lookup

ADDED in v3.0:

• ✅ Optional "Domain" field
• ✅ Skills auto-load via globs during implementation

Why:

• Main agent implements directly (no delegation)
• Skills activate based on files edited
• Simpler story template
• Domain tracking for business docs

Story Template Fields

Story structure, field names, and ordering are defined in specwright/templates/docs/story-template.md (see "Story Format" section at the top of this skill). Follow the template exactly — do not paraphrase the field names or change the section structure.

---

Project-Specific Standards

Architecture Standards

<!-- From specwright/product/architecture-decision.md or architecture/platform-architecture.md -->

[ARCHITECTURE_PATTERNS]

Project Structure

<!-- From specwright/product/architecture-structure.md -->

[PROJECT_STRUCTURE]

Naming Conventions

[NAMING_CONVENTIONS]

---

Quality Standards Reference

For full DoD criteria see: specwright/team/dod.md For full DoR criteria see: specwright/team/dor.md