codeforge-dev 1.5.7 → 1.7.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/specification-writing/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: specification-writing
+description: >-
+  This skill should be used when the user asks to "write a specification",
+  "create requirements", "define acceptance criteria", "write user stories",
+  "create a feature spec", "document requirements", "use EARS format",
+  "write Given/When/Then scenarios", "define edge cases for a feature",
+  "structure a product requirement document",
+  or discusses requirement formats, EARS templates, Gherkin syntax,
+  acceptance criteria patterns, specification structure,
+  or completeness checklists for feature definitions.
+version: 0.1.0
+---
+
+# Specification Writing
+
+## Mental Model
+
+Specifications are **contracts between humans** -- between the person requesting a feature and the person building it. The goal is to eliminate ambiguity so that both parties agree on what "done" means before work begins.
+
+A specification is not prose. It's a structured document with testable claims. Every requirement should be verifiable: can you write a test (automated or manual) that proves the requirement is met? If you can't test it, it's not a requirement -- it's a wish.
+
+The most common source of project failure is not bad code but bad specifications. Specifically:
+- **Missing edge cases** -- "What happens when the list is empty?"
+- **Ambiguous language** -- "The system should respond quickly" (how quickly?)
+- **Implicit assumptions** -- "Users will authenticate" (how? OAuth? Password? SSO?)
+- **Missing error cases** -- "The system saves the file" (what if the disk is full?)
+
+Write specifications with a hostile reader in mind -- someone who will interpret every ambiguity in the worst possible way. If a requirement can be misunderstood, it will be.
+
+---
+
+## EARS Requirement Formats
+
+EARS (Easy Approach to Requirements Syntax) provides five templates that eliminate the most common ambiguities in natural-language requirements. Each template has a specific trigger pattern.
+
+### Ubiquitous
+
+Requirements that are always active, with no trigger condition:
+
+```
+The <system> shall <action>.
+```
+
+**Example:** The API shall return responses in JSON format.
+
+### Event-Driven
+
+Requirements triggered by a specific event:
+
+```
+When <event>, the <system> shall <action>.
+```
+
+**Example:** When a user submits a login form with invalid credentials, the system shall display an error message and increment the failed login counter.
+
+### State-Driven
+
+Requirements that apply while the system is in a specific state:
+
+```
+While <state>, the <system> shall <action>.
+```
+
+**Example:** While the system is in maintenance mode, the API shall return HTTP 503 for all non-health-check endpoints.
+
+### Unwanted Behavior
+
+Requirements for handling error conditions and edge cases:
+
+```
+If <condition>, then the <system> shall <action>.
+```
+
+**Example:** If the database connection pool is exhausted, then the system shall queue incoming requests for up to 30 seconds before returning HTTP 503.
+
+### Optional Feature
+
+Requirements that depend on a configurable feature:
+
+```
+Where <feature is enabled>, the <system> shall <action>.
+```
+
+**Example:** Where two-factor authentication is enabled, the system shall require a TOTP code after successful password verification.
+
+> **Deep dive:** See `references/ears-templates.md` for EARS format templates with filled examples for each pattern type.
+
+---
+
+## Acceptance Criteria Patterns
+
+Acceptance criteria define when a requirement is satisfied. Use these patterns to write criteria that are directly testable.
+
+### Given/When/Then (Gherkin)
+
+The most structured pattern. Each scenario is a test case:
+
+```gherkin
+Feature: User Login
+
+  Scenario: Successful login with valid credentials
+    Given a registered user with email "alice@example.com"
+    And the user has a verified account
+    When the user submits the login form with correct credentials
+    Then the system returns a 200 response with an auth token
+    And the auth token expires in 24 hours
+
+  Scenario: Failed login with invalid password
+    Given a registered user with email "alice@example.com"
+    When the user submits the login form with an incorrect password
+    Then the system returns a 401 response
+    And the failed login attempt is logged
+    And the response does not reveal whether the email exists
+```
+
+**When to use:** Complex workflows with multiple actors, preconditions, or state transitions. Best for user-facing features.
+
+### Checklist
+
+A flat list of verifiable statements. Simpler than Gherkin but less precise:
+
+```markdown
+## Acceptance Criteria: Password Reset
+
+- [ ] User receives reset email within 60 seconds of request
+- [ ] Reset link expires after 1 hour
+- [ ] Reset link is single-use (invalidated after first use)
+- [ ] Password must meet strength requirements (min 12 chars, 1 uppercase, 1 number)
+- [ ] All existing sessions are invalidated after password change
+- [ ] User receives confirmation email after successful reset
+```
+
+**When to use:** Simpler features where the preconditions are obvious and each criterion is independent.
+
+### Table-Driven
+
+For requirements with multiple input/output combinations:
+
+```markdown
+## Discount Rules
+
+| Customer Type | Order Total | Discount | Notes |
+|---------------|-------------|----------|-------|
+| Standard      | < $50       | 0%       | |
+| Standard      | >= $50      | 5%       | |
+| Premium       | < $50       | 5%       | Minimum premium discount |
+| Premium       | >= $50      | 10%     | |
+| Premium       | >= $200     | 15%     | Max discount cap |
+| Employee      | any         | 25%      | Requires valid employee ID |
+```
+
+**When to use:** Business rules with multiple conditions and outcomes. The table format makes gaps and overlaps visible.
+
+> **Deep dive:** See `references/criteria-patterns.md` for acceptance criteria examples across different domains.
+
+---
+
+## Specification Structure
+
+A complete specification follows this structure. Not every section is needed for every feature -- scale the document to the complexity.
+
+### 1. Problem Statement
+What problem does this feature solve? Who has this problem? What's the cost of not solving it? (2-3 sentences)
+
+### 2. Scope
+What's in scope and what's explicitly out of scope? Out-of-scope items prevent scope creep.
+
+```markdown
+## Scope
+
+**In scope:**
+- User-initiated password reset via email
+- Password strength validation
+- Session invalidation on reset
+
+**Out of scope:**
+- Admin-initiated password reset (separate spec)
+- Password expiration policies
+- Account recovery without email access
+```
+
+### 3. User Stories
+Who are the actors and what do they want to achieve?
+
+```markdown
+As a [registered user], I want to [reset my password via email]
+so that [I can regain access to my account when I forget my password].
+
+As a [security admin], I want to [see password reset audit logs]
+so that [I can detect suspicious reset patterns].
+```
+
+### 4. Functional Requirements
+Use EARS format. Number each requirement for traceability:
+
+```markdown
+- FR-1: When a user requests a password reset, the system shall send a reset email
+  to the registered email address within 60 seconds.
+- FR-2: The reset link shall contain a cryptographically random token (min 32 bytes).
+- FR-3: If the reset token is expired or already used, then the system shall display
+  an error message and offer to send a new reset email.
+```
+
+### 5. Non-Functional Requirements
+Performance, security, scalability, accessibility:
+
+```markdown
+- NFR-1: The password reset endpoint shall respond within 200ms (p95).
+- NFR-2: Reset tokens shall be stored as bcrypt hashes, not plaintext.
+- NFR-3: The reset flow shall be accessible with screen readers (WCAG 2.1 AA).
+```
+
+### 6. Edge Cases
+The cases nobody thinks about until they happen:
+
+```markdown
+- What if the user requests multiple resets before using any link?
+  → Only the most recent token is valid; previous tokens are invalidated.
+- What if the email is associated with multiple accounts?
+  → Send separate reset links for each account.
+- What if the user's email provider is down?
+  → The system logs the failure and retries up to 3 times over 5 minutes.
+```
+
+### 7. Out of Scope
+Explicit non-goals to prevent scope creep (can reference the Scope section or expand here).
+
+---
+
+## Completeness Checklist
+
+Before marking a specification as ready for implementation, verify:
+
+**Happy path:**
+- [ ] Primary use case described with acceptance criteria
+- [ ] All actors identified (user, admin, system, external service)
+- [ ] Success response/outcome defined
+
+**Error cases:**
+- [ ] Invalid input handled (empty, too long, wrong type, malicious)
+- [ ] External service failures handled (timeout, 500, unavailable)
+- [ ] Concurrent access conflicts addressed
+- [ ] Rate limiting defined for public-facing endpoints
+
+**Boundary conditions:**
+- [ ] Empty collections (zero items)
+- [ ] Maximum limits defined (max file size, max items, max length)
+- [ ] Pagination for unbounded lists
+- [ ] Time zones and date boundaries
+
+**Performance:**
+- [ ] Response time targets (p50, p95, p99)
+- [ ] Throughput requirements (requests per second)
+- [ ] Data volume expectations (rows, storage size)
+
+**Security:**
+- [ ] Authentication required? Which methods?
+- [ ] Authorization rules per role
+- [ ] Data sensitivity classification
+- [ ] Audit logging requirements
+
+**Accessibility:**
+- [ ] WCAG compliance level specified
+- [ ] Keyboard navigation requirements
+- [ ] Screen reader compatibility
+
+---
+
+## Ambiguity Policy
+
+These defaults apply when the user does not specify a preference. State the assumption when making a choice:
+
+- **Format:** Default to EARS format for requirements and Given/When/Then for acceptance criteria. Use checklists for simple features with obvious preconditions.
+- **Detail level:** Default to enough detail that a developer unfamiliar with the codebase could implement the feature without asking clarifying questions.
+- **Non-functional requirements:** Always include response time targets (default: 200ms p95 for API endpoints, 3s for page loads) and note when these are assumptions.
+- **Edge cases:** Always include at least: empty input, maximum input, concurrent access, and external service failure.
+- **Out of scope:** Always include an out-of-scope section, even if brief, to establish boundaries.
+- **Numbering:** Number all requirements (FR-1, NFR-1) for traceability in code reviews and tests.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/ears-templates.md` | EARS format templates with filled examples for each pattern type, including compound requirements and requirement hierarchies |
+| `references/criteria-patterns.md` | Acceptance criteria examples organized by domain: authentication, payments, file upload, search, notifications, and data import |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/specification-writing/references/criteria-patterns.md

@@ -0,0 +1,245 @@
+# Acceptance Criteria Patterns by Domain
+
+Examples of acceptance criteria organized by common feature domains.
+
+## Contents
+
+- [Authentication](#authentication)
+- [Payments](#payments)
+- [File Upload](#file-upload)
+- [Search](#search)
+- [Notifications](#notifications)
+- [Data Import](#data-import)
+- [Cross-Domain Edge Cases](#cross-domain-edge-cases)
+
+---
+
+## Authentication
+
+### Login Flow
+
+```gherkin
+Feature: User Login
+
+  Scenario: Successful login with email and password
+    Given a verified user with email "alice@example.com"
+    When the user submits the login form with correct credentials
+    Then the system returns a 200 response with an auth token
+    And the token expires in 24 hours
+    And a "login_success" event is logged with the user ID
+
+  Scenario: Login with unverified email
+    Given a user with email "bob@example.com" who has not verified their email
+    When the user submits the login form with correct credentials
+    Then the system returns a 403 response
+    And the response body contains "Please verify your email address"
+    And a new verification email is sent
+
+  Scenario: Login with invalid credentials
+    Given no user exists with email "unknown@example.com"
+    When the user submits the login form with email "unknown@example.com"
+    Then the system returns a 401 response
+    And the response body contains "Invalid email or password"
+    And the response time is similar to a valid-email failure (timing-safe)
+
+  Scenario: Account lockout after repeated failures
+    Given a user with email "alice@example.com"
+    When the user submits 5 incorrect passwords within 10 minutes
+    Then the account is locked for 15 minutes
+    And subsequent login attempts return "Account temporarily locked"
+    And a security alert email is sent to the user
+```
+
+### Password Reset
+
+**Checklist format:**
+
+- [ ] Reset email sent within 60 seconds of request
+- [ ] Reset token is a cryptographically random 32-byte value
+- [ ] Token expires after 1 hour
+- [ ] Token is single-use (invalidated after first use)
+- [ ] Using an expired or used token shows "This link has expired" with option to request a new one
+- [ ] New password must meet strength requirements
+- [ ] All existing sessions invalidated after successful reset
+- [ ] Reset request for non-existent email returns success (no enumeration)
+- [ ] Rate limited to 3 reset requests per email per hour
+
+---
+
+## Payments
+
+### Checkout Flow
+
+```gherkin
+Feature: Order Checkout
+
+  Scenario: Successful payment
+    Given a cart with items totaling $49.99
+    And the user has a valid payment method on file
+    When the user confirms the checkout
+    Then the payment is authorized for $49.99
+    And the order status changes to "confirmed"
+    And a confirmation email is sent with the order details
+    And inventory is decremented for each item
+
+  Scenario: Payment declined
+    Given a cart with items totaling $49.99
+    When the payment gateway returns "card_declined"
+    Then the order status remains "pending"
+    And the user sees "Your card was declined. Please try another payment method."
+    And inventory is NOT decremented
+    And no confirmation email is sent
+
+  Scenario: Payment gateway timeout
+    Given a cart with items totaling $49.99
+    When the payment gateway does not respond within 10 seconds
+    Then the system retries once after 3 seconds
+    And if the retry also fails, shows "Payment processing is delayed"
+    And the order enters "payment_pending" status
+    And a background job checks payment status every 60 seconds for 30 minutes
+```
+
+### Discount Rules
+
+**Table-driven format:**
+
+| Customer Type | Order Total | Coupon | Expected Discount | Final Price |
+|---------------|-------------|--------|-------------------|-------------|
+| Standard      | $30.00      | None   | 0%                | $30.00      |
+| Standard      | $30.00      | SAVE10 | 10%               | $27.00      |
+| Premium       | $30.00      | None   | 5%                | $28.50      |
+| Premium       | $30.00      | SAVE10 | 10% (higher wins) | $27.00      |
+| Premium       | $100.00     | SAVE10 | 15% (premium tier) | $85.00     |
+| Any           | $0.00       | SAVE10 | 0%                | $0.00       |
+| Standard      | $30.00      | EXPIRED| 0% + error shown  | $30.00      |
+
+---
+
+## File Upload
+
+### Image Upload
+
+```gherkin
+Feature: Profile Image Upload
+
+  Scenario: Successful image upload
+    Given the user is on the profile settings page
+    When the user uploads a valid JPEG image under 5MB
+    Then the image is resized to 256x256 pixels
+    And the image is stored in the CDN
+    And the user's profile displays the new image within 5 seconds
+
+  Scenario: File too large
+    When the user uploads an image larger than 5MB
+    Then the upload is rejected before the file is fully transferred
+    And the error message reads "Image must be under 5MB. Your file is [X]MB."
+
+  Scenario: Invalid file type
+    When the user uploads a .exe file renamed to .jpg
+    Then the system validates the file's MIME type (not just extension)
+    And rejects the upload with "Supported formats: JPEG, PNG, WebP"
+
+  Scenario: Concurrent uploads
+    When the user uploads two images simultaneously
+    Then only the last uploaded image is saved as the profile picture
+    And both uploads complete without errors
+```
+
+---
+
+## Search
+
+### Full-Text Search
+
+**Checklist format:**
+
+- [ ] Empty search query returns validation error, not all results
+- [ ] Search results appear within 500ms for queries across 1M documents
+- [ ] Results are ranked by relevance (BM25 or equivalent)
+- [ ] Search highlights matching terms in results with `<mark>` tags
+- [ ] Queries with no results show "No results found" with spelling suggestions
+- [ ] Special characters in queries are escaped (no injection)
+- [ ] Results are paginated with 20 items per page
+- [ ] Search query is preserved in the URL for shareability
+- [ ] Minimum query length: 2 characters
+- [ ] Maximum query length: 200 characters
+
+---
+
+## Notifications
+
+### Email Notifications
+
+```gherkin
+Feature: Notification Preferences
+
+  Scenario: User opts out of marketing emails
+    Given a user subscribed to all notification types
+    When the user unchecks "Marketing updates" in notification preferences
+    Then marketing emails stop within 24 hours
+    And transactional emails (receipts, password resets) continue normally
+    And the preference change is logged for compliance
+
+  Scenario: Notification delivery failure
+    Given a notification is queued for delivery
+    When the email provider returns a 5xx error
+    Then the system retries after 1 minute, 5 minutes, and 30 minutes
+    And after 3 failures, marks the notification as "failed"
+    And does NOT send further retries for this notification
+    And the failure is recorded in the admin dashboard
+```
+
+---
+
+## Data Import
+
+### CSV Import
+
+```gherkin
+Feature: User Data Import
+
+  Scenario: Valid CSV import
+    Given an admin uploads a CSV with 500 valid user records
+    When the import is processed
+    Then all 500 users are created with correct field mapping
+    And the admin sees a summary: "500 created, 0 skipped, 0 errors"
+    And each user receives a welcome email
+
+  Scenario: CSV with validation errors
+    Given a CSV where row 3 has an invalid email and row 7 has a duplicate email
+    When the import is processed
+    Then valid rows (498) are imported successfully
+    And invalid rows are skipped with error details:
+      | Row | Field | Error |
+      | 3   | email | "not.valid" is not a valid email format |
+      | 7   | email | "alice@example.com" already exists |
+    And the admin can download an error report CSV
+
+  Scenario: Large file import
+    Given a CSV with 100,000 records
+    When the import is initiated
+    Then the import runs asynchronously (not blocking the UI)
+    And the admin sees a progress indicator
+    And the import completes within 5 minutes
+    And the system sends an email when import finishes
+```
+
+---
+
+## Cross-Domain Edge Cases
+
+These edge cases apply to most features and should be checked:
+
+```markdown
+## Universal Edge Cases
+
+- [ ] Empty input: What happens when required fields are blank?
+- [ ] Maximum length: What happens at the field's max length? At max + 1?
+- [ ] Unicode: Does the feature handle emoji, CJK characters, RTL text?
+- [ ] Concurrent access: What if two users edit the same resource simultaneously?
+- [ ] Network interruption: What if connectivity drops mid-operation?
+- [ ] Timezone: Do date-dependent features work correctly across timezones?
+- [ ] Pagination boundary: What happens when viewing the last page as items are deleted?
+- [ ] Authorization: Can the feature be accessed without authentication? With wrong role?
+- [ ] Idempotency: What happens if the same request is sent twice?
+```