Story Craftsman

This skill embodies the "Everything is Code" engineering philosophy, helping you produce high-quality user stories and their supporting documentation alongside your MR submissions.

For the detailed example template, see examples/TEMPLATE-UserStory.md.

Rules

1. Never fabricate information: When information is insufficient, obtain context through guided interviews rather than filling in details yourself
2. Architecture-aware placement: Analyze file paths or git status to determine the relevant module and place documents in the corresponding docs/04-user-stories/ directory
3. Testable acceptance criteria: Each AC must be a verifiable, checkable condition (Given/When/Then or clear checkbox)
4. Consolidate questions: During interviews, combine all missing dimensions into a single round of questions to avoid multi-round fragmented asking that causes user fatigue
5. Path-first inference: First attempt to infer the target sub-module from context; only ask the user when uncertain

Execution Flow

Feature A: Generate User Story

Trigger Conditions

User requests "help me write a User Story," "describe this feature," "generate user story," etc.

Step 1: Assess Information Sufficiency

After receiving a request, check whether the following three elements are present:

If information is insufficient, execute Step 2 (interview); if sufficient, proceed directly to Step 3 (generation).

Step 2: Guided Interview Protocol

Take on the dual role of "detective" and "poet," asking all missing dimension questions in a single round (avoiding multi-round fragmented questions):

To generate a professional user story, I need you to confirm the following (keep it brief, 1-3 sentences per item):

1. **Background/Pain point**: [specific missing background question]
2. **Goal**: [specific missing goal question]
3. **Acceptance criteria**: [specific missing AC question]

You can describe briefly — I will handle converting it into the standard professional document format.

Step 3: Generate User Story File

Strictly follow the structure from TEMPLATE-UserStory.md to generate the file.

File naming convention: {feature-name}.md (lowercase kebab-case)

Placement path: {submodule_root}/docs/04-user-stories/{feature-name}.md

If the target directory does not exist, first execute Feature B or prompt the user.

Feature B: Initialize Standard Docs Structure

Trigger Conditions

User explicitly requests "create docs structure," "initialize docs," etc.

Standard Directory Structure

docs/
├── 01-product-research/    # Product research and competitive analysis
├── 02-system-design/       # System design and architecture decisions
├── 03-detailed-design/     # Detailed design documents
├── 04-user-stories/        # User Stories
└── 05-user-guide/          # User manuals and operation guides

Execution Steps

1. Confirm the target root directory (ask the user or infer from context)
2. Create the 5 subdirectories listed above under the target root
3. Create a .gitkeep file in each subdirectory to ensure Git tracks empty directories
4. Generate AGENTS.md in the docs/ root directory describing each directory's purpose

Generated docs/AGENTS.md Content Template

# docs/

This directory is the project documentation root, organized by R&D lifecycle stages.

## Directory Structure

- `01-product-research/`: Product research, competitive analysis, market insights
- `02-system-design/`: System architecture design, technology selection, ADR (Architecture Decision Records)
- `03-detailed-design/`: Module detailed design, interface specifications, data structures
- `04-user-stories/`: User Story files, naming convention: `{feature-name}.md`
- `05-user-guide/`: End-user operation manuals and usage instructions

## Maintenance Conventions

- User stories are created as individual `.md` files per feature module
- This file should be updated after architectural/directory-level changes

Sub-Module Identification Logic

Analyze code changes or user descriptions to determine the target sub-module in the following order:

1. Infer from file paths: Top-level directory of changed files (e.g., device-cloud-server/, frontend/)
2. Infer from git status: Path prefixes in git status output
3. Ask when uncertain: If changes span multiple modules or paths are unclear, must ask the user

Examples

Bad

## User Story: Alarm Filtering Feature

**As** a system administrator, **I want** to filter alarms, **so that** I can reduce distractions.

**Acceptance Criteria**:
- [ ] System supports filtering functionality
- [ ] Filtered alarms are not displayed after filtering

Problem: Missing background, ACs are too vague, unable to verify "what conditions trigger filtering."

Good

## User Story: Rule-Based Alarm Silence Filtering

**Background**: The monitoring system generates 500+ heartbeat probe alarms daily, causing
operator alert fatigue. Real fault alarms get buried, and average response time has increased
from 2 minutes to 15 minutes.

**As** an operations engineer, **I want** to configure alarm silence rules (by device type + alarm type combination),
**so that** known non-fault alarms are suppressed and real fault alarm response time returns to under 2 minutes.

**Acceptance Criteria**:
- [ ] Given a configured silence rule "device type=heartbeat probe AND alarm type=connection timeout,"
      When such an alarm fires, Then the Grafana dashboard does not display it and the audit log records "silenced"
- [ ] Given the silence rule configuration interface, When the admin saves a rule,
      Then the rule takes effect within 30 seconds without requiring a service restart
- [ ] Given an alarm matches both a silence rule and an escalation rule simultaneously,
      When the alarm fires, Then the silence rule takes priority, but the conflict is noted in the audit log

Exemptions

Exemption method: /override skill=story-craftsman reason="pure technical refactoring, no user-visible functionality change"

References

• User Story Template
• INVEST Principles — Independent, Negotiable, Valuable, Estimable, Small, Testable
• Given-When-Then Acceptance Criteria Writing