Optimize skill descriptions and content for better triggering

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 **/.DS_Store
 reference
+skills-workspace

skills/requirement-decomposer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: requirement-decomposer
-description: "Use when decomposing specifications into agile delivery artifacts — creating epics from use cases, breaking epics into user stories, planning releases or sprints, or running backlog refinement. Provides two-layer architecture rules, decomposition heuristics, INVEST criteria, and Given/When/Then derivation."
+description: "Invoke for any agile delivery task: break a use case (UC) into an epic and user stories, estimate story points for a feature, calculate sprint capacity from team size and availability, adjust a sprint plan when velocity drops, or lay out a release timeline across sprints. Handles the full spec-to-backlog pipeline — mapping UC steps to stories, sizing work items, planning iterations, and running backlog refinement. Trigger on: 'convert to work items', 'break into stories', 'how many points', 'sprint capacity', 'velocity', 'release plan', 'size this', 'make this sprint-ready', 'prioritize the backlog', PTO/availability planning, or any question about fitting features into sprints. Provides two-layer architecture rules, decomposition heuristics, step-to-story mapping, INVEST criteria, story sizing guide, and Given/When/Then acceptance criteria derivation."
 user-invocable: false
 ---
 
@@ -53,6 +53,44 @@ See [acceptance-criteria.md](acceptance-criteria.md) for how to derive Given/Whe
 | 8 | Large, complex logic | Hierarchical class picker with inheritance |
 | 13 | Very large — **must split** | End-to-end flow with integration |
 
+## Handling Incomplete Specs
+
+When decomposing a spec that has gaps (missing fields, TBD sections, incomplete exception flows):
+1. **Flag gaps explicitly** — list what's missing and how it affects decomposition
+2. **Decompose what you can** — create stories for the complete portions
+3. **Create placeholder stories** — for TBD areas, create stories marked as "Draft" with a note: "Blocked: awaiting spec completion for [section]"
+4. **Suggest spec completion** — recommend the user fill in the gaps with `/review-spec <code>` or by editing the spec directly
+
+Never silently invent requirements to fill gaps. Always surface missing information.
+
+## Decomposition Example
+
+Given a Use Case with steps like:
+```
+1. User opens the Create Order form
+2. System displays form with project context
+3. User selects category from dropdown
+4. System auto-populates inherited fields
+5. User fills remaining fields and clicks Save
+6. System validates and creates the order
+```
+
+The decomposition produces:
+- **Story 1**: "Display Create Order form with project context" (steps 1-2)
+- **Story 2**: "Select Category with hierarchical dropdown" (step 3)
+- **Story 3**: "Auto-populate inherited fields on category selection" (step 4)
+- **Story 4**: "Validate and save Order record" (steps 5-6)
+
+Each story gets ACs derived from the UC steps, exception flows, and business rules using the patterns in [acceptance-criteria.md](acceptance-criteria.md).
+
+## Sprint Capacity Planning
+
+When planning sprints:
+- **Velocity estimation**: If no historical data, assume 8 SP/developer/sprint for a 2-week sprint
+- **Buffer**: Plan 70-80% of capacity (leave room for bugs, tech debt, meetings)
+- **Dependencies**: Data model stories before UI stories, API stories before integration stories
+- **Risk**: Front-load high-risk or uncertain stories so blockers surface early
+
 ## Reference
 
 See `templates/README.md` for the full guide on how specification and delivery layers connect.

skills/spec-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-writer
-description: "Use when writing, creating, or editing any specification or delivery document — SRS overviews, objects, use cases, screens, business rules, actors, workflows, state transitions, permission matrices, NFRs, interfaces, decision tables, meeting notes, epics, user stories, sprints, release plans, or backlog refinements. Provides template selection, naming conventions, quality guidance, dynamic domain discovery, conflict detection, and spec lifecycle management."
+description: "Spec out software requirements. Use whenever the user wants to define, document, or design any part of a software system: data models and objects ('define the Item object'), screen layouts and UI specs ('write a screen spec for the dashboard'), use cases and workflows ('how does the user create an order?'), state transitions and lifecycles ('Invoice: Draft → Sent → Paid'), decision tables, business rules, permission matrices ('who can approve purchase orders?'), actor definitions, interface contracts, NFRs, meeting notes with requirement extraction, change requests, impact analyses, phase deltas, SRS overviews, and delivery artifacts like epics, user stories, sprints, release plans, and backlog refinements. Also trigger when the user asks 'what template should I use', wants to modify an approved spec (Phase 2 delta pattern), or is describing system structure, behavior, rules, or requirements and wants a structured document. Provides template selection, auto-numbering, naming conventions, IEEE 830/ISO 29148 quality guidance, dynamic domain discovery, conflict detection, cross-reference validation, and spec lifecycle management."
 user-invocable: false
 ---
 
@@ -116,6 +116,27 @@ When creating or editing a spec, validate all referenced codes:
 - If a referenced spec does not exist, warn the user and suggest creating it with `/new-spec`
 - If creating a spec that should reference existing artifacts (e.g., a Screen should reference its Use Case), proactively suggest the cross-references
 
+## SRS Overview Creation
+
+When the user is starting a new project or system, create the SRS Overview first — it's the parent document that indexes all other specs. Use `templates/software_spec/srs_overview.template.md` and place it at `docs/spec/SRS<NN>_<Name>.md`.
+
+The SRS Overview contains:
+- Scope, glossary, and constraints (§1-4)
+- Object Relationship Diagram section (§7.5)
+- Use Case Groupings (§5.2)
+- Traceability & Coverage (§8)
+
+Update the SRS Overview whenever new spec artifacts are created to keep the index current.
+
+## Change Request & Impact Analysis Creation
+
+When the user reports a requirement change or mentions that something needs to change in approved specs:
+1. Create a Change Request using `templates/software_spec/input_management/change_request.template.md` → `docs/spec/change_requests/CR-NNNN_<Title>.md`
+2. Suggest running `/impact-analysis <CR code>` to assess blast radius
+3. After CR approval, guide the user to `/apply-change` or `/phase-delta` for implementation
+
+See `templates/software_spec/input_management/change_management_rules.md` for CR lifecycle rules, risk criteria, and sprint protection.
+
 ## Reference
 
 See `templates/README.md` for the full guide on how specification and delivery layers connect.

skills/traceability-checker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: traceability-checker
-description: "Use when verifying cross-references, checking requirement traceability, finding orphan specs or stories, validating coverage completeness, or building a traceability matrix. Provides forward/backward traceability rules, cross-reference validation, and coverage metrics."
+description: "Trigger whenever the user asks to check, validate, or audit connections between requirements artifacts. This includes: cross-reference checking between screens, specs, and use cases; building traceability matrices; finding orphaned or unlinked specs, stories, or epics; generating coverage reports; or asking questions like 'what's missing', 'what's not covered', 'is everything linked', 'are requirements covered', 'find gaps', 'check my cross-references', or 'what specs don't have stories yet'. Use for any verification of existing spec-to-delivery linkage — not for creating or writing new specs, stories, or use cases. Also use before sprint starts to verify story-to-spec traceability, or after creating new specs to check they're properly linked. Provides forward/backward traceability rules, cross-reference validation, coverage metrics, orphan detection, broken reference scanning, and structured reporting."
 user-invocable: false
 ---
 
@@ -68,6 +68,36 @@ Report findings as a structured table:
 | BRs referenced by UCs | N / N | NN% |
 ```
 
+## Check Modes
+
+### Full Scan (default for `/check-traceability`)
+Scans all specs and delivery artifacts across the entire `docs/` directory. Use when:
+- Starting a new sprint or release
+- After a batch of specs have been created
+- Before presenting traceability to stakeholders
+
+### Focused Check (for a specific scope)
+When the user specifies a scope (e.g., a single epic, spec, or directory), only scan the relevant artifacts and their direct references. Use when:
+- The user just created a new spec and wants to verify it's linked properly
+- Checking a single epic's stories before sprint planning
+- Validating a Phase 2 delta's cross-references
+
+For focused checks, still report any broken outbound references (e.g., if the new spec references a UC that doesn't exist), but don't report unrelated orphans.
+
+### Quick Validation (after single artifact creation)
+When a single spec or story was just created, do a lightweight check:
+1. Verify the new artifact's outbound references exist
+2. Check if any existing specs should reference the new artifact but don't
+3. Report only issues related to the new artifact
+
+## Common Patterns to Flag
+
+- **Orphan Business Rules**: BR specs not referenced by any UC — often indicates the rule was defined but never wired into a use case
+- **Stories without ACs**: User stories missing Given/When/Then — blocks sprint readiness
+- **One-way references**: UC references a Screen, but Screen doesn't reference back to the UC
+- **Phantom codes**: A spec references `UC0005` but no file with that code exists
+- **TBD overload**: Specs with more than 3 unresolved TBDs — flag for completion before decomposition
+
 ## Reference
 
 - Traceability content: SRS Overview §8 (Traceability & Coverage) in `templates/software_spec/srs_overview.template.md`