@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/requesting-code-review/references/self-review-checklist.md

@@ -1,121 +0,0 @@
-# Self-Review Checklist
-
-## Overview
-
-Self-review is the highest-ROI activity in the code review process. Catching your own mistakes before requesting review builds trust, reduces review cycles, and trains your eye for quality. This checklist is designed to be completed in 10-15 minutes on a typical PR before assigning reviewers.
-
-## Before You Start
-
-- [ ] Close your IDE and review the diff in the PR interface (GitHub, GitLab, etc.) — you will see the code differently in a new context.
-- [ ] Read your own PR description — does it make sense to someone without your context?
-- [ ] Check the file list — are there any files that should not be in this PR (debug logs, unrelated changes, generated files)?
-
-## Diff Review
-
-### Accidental Inclusions
-
-- [ ] No `console.log`, `print()`, `debugger`, or `binding.pry` statements left in
-- [ ] No commented-out code that should be deleted
-- [ ] No TODO comments without a linked issue
-- [ ] No unrelated formatting changes mixed with functional changes
-- [ ] No accidental file permission changes
-- [ ] No secrets, API keys, or credentials in the diff
-- [ ] No large binary files or data files committed accidentally
-- [ ] `.gitignore` has not been weakened to include files that should be excluded
-
-### Completeness
-
-- [ ] Every changed behavior has a corresponding test
-- [ ] Error paths return appropriate status codes and messages
-- [ ] New API endpoints are documented (OpenAPI, README, or inline)
-- [ ] New environment variables are documented and have defaults
-- [ ] Database migrations have corresponding rollback migrations
-- [ ] New dependencies are justified and pinned to a version
-
-### Correctness
-
-- [ ] Variable names accurately describe their contents
-- [ ] Function signatures match their documented behavior
-- [ ] Edge cases are handled: null, empty, zero, negative, maximum
-- [ ] Async operations are properly awaited (no floating promises)
-- [ ] Resources are cleaned up in error paths (connections, file handles, locks)
-- [ ] Loop invariants are correct (off-by-one, empty collection, infinite loop)
-
-### Security
-
-- [ ] User input is validated before use
-- [ ] SQL queries use parameterized statements (no string concatenation)
-- [ ] HTML output is escaped or uses auto-escaping templates
-- [ ] Authentication checks are present on protected endpoints
-- [ ] Authorization checks verify the user can access the specific resource
-- [ ] Sensitive data is not logged or exposed in error messages
-
-### Performance
-
-- [ ] No N+1 query patterns (queries inside loops)
-- [ ] Large result sets are paginated
-- [ ] Expensive operations are not repeated unnecessarily
-- [ ] New database queries use appropriate indexes (check with EXPLAIN)
-- [ ] Frontend changes do not add unnecessary re-renders or large bundle size
-
-## Commit History Review
-
-- [ ] Commits tell a logical story when read in order
-- [ ] Each commit compiles and passes tests independently
-- [ ] Commit messages are descriptive (not "fix", "wip", "stuff")
-- [ ] No fixup commits that should be squashed into their parent
-- [ ] Merge commits are clean (no accidental conflict resolution artifacts)
-
-## PR Metadata Review
-
-- [ ] Title is concise, imperative mood, under 72 characters
-- [ ] Description includes What, Why, and How
-- [ ] Related issues are linked with closing keywords (Fixes #123)
-- [ ] Labels are applied (bug, feature, refactor, etc.)
-- [ ] Milestone or sprint is set if required by team process
-- [ ] Draft status is correct (draft for early feedback, ready for final review)
-
-## Test Review
-
-- [ ] All new tests pass locally
-- [ ] Tests cover the happy path and at least one error path
-- [ ] Tests are deterministic (no time-dependent or order-dependent)
-- [ ] Test names describe the behavior being tested, not the implementation
-- [ ] Mocks are realistic and match the real API contract
-- [ ] No tests were deleted without explanation
-
-## Visual Review (UI Changes Only)
-
-- [ ] Before/after screenshots are attached to the PR
-- [ ] UI renders correctly at common breakpoints (mobile, tablet, desktop)
-- [ ] Interactive elements are keyboard-accessible
-- [ ] Color contrast meets WCAG AA (4.5:1 for normal text)
-- [ ] Loading states and error states are handled
-- [ ] Text is not truncated or overflowing
-
-## Final Check
-
-- [ ] CI pipeline passes (do not request review with failing CI)
-- [ ] Branch is up to date with the target branch (no stale conflicts)
-- [ ] The change is complete — no "I will fix this in a follow-up" without a linked issue
-- [ ] You can explain every line of the diff if asked
-
-## When Self-Review Finds Issues
-
-If self-review reveals problems:
-
-1. **Fix them before requesting review** — do not rely on reviewers to catch issues you already found.
-2. **Add inline PR comments** on decisions that might look wrong but are intentional — this prevents reviewers from flagging the same things.
-3. **Update the PR description** if the fix changed the approach or introduced new limitations.
-4. **Reset the review if you push significant changes** — reviewers should not approve a diff that changed substantially after their review.
-
-## Time Budget
-
-| PR Size           | Self-Review Time | When to Spend More |
-|-------------------|------------------|--------------------|
-| Small (<50 lines) | 5 minutes        | Security-sensitive changes |
-| Medium (50-200)   | 10 minutes       | Multiple files, new APIs |
-| Large (200-500)   | 15-20 minutes    | Always — large PRs need thorough self-review |
-| Very large (500+) | 20-30 minutes    | Consider splitting the PR instead |
-
-Self-review time is never wasted. Every issue you catch yourself is a review cycle you did not need, a reviewer interaction you did not wait for, and trust you built for the next review.

package/workflows/skills/sadd/SKILL.md

@@ -1,64 +0,0 @@
----
-name: sadd
-description: "Use when extracting testable specs from requirements, generating tests from specs, verifying implementations against specs, and tracing requirements to coverage."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: "Claude Code, Codex, GitHub Copilot"
----
-
-# Spec-Aware Driven Development (SADD)
-
-## Purpose
-
-Bridge the gap between requirements and implementation by extracting machine-verifiable specifications from natural language requirements, generating tests that encode those specifications, and continuously verifying that the implementation satisfies every stated requirement. SADD prevents the common failure mode where code is "done" but does not match what was specified.
-
-## When to Use
-
-- Extracting testable specifications from a requirements document, user story, or PRD
-- Generating test cases directly from specifications before writing implementation code
-- Verifying that an existing implementation satisfies a specification
-- Building a traceability matrix from requirements to tests to code
-- Identifying specification gaps where requirements are ambiguous or incomplete
-- Auditing test coverage against requirements (not just code coverage)
-- Onboarding to a codebase by understanding what it is supposed to do vs what it actually does
-- Preparing for compliance audits that require requirements traceability
-
-## Instructions
-
-1. **Gather the specification source** — collect all requirements documents, user stories, acceptance criteria, API contracts, and design documents, because SADD cannot extract specs from what it cannot see.
-2. **Mine specifications from requirements** — extract every testable assertion from the source material using the GIVEN-WHEN-THEN format, because natural language requirements contain implicit conditions that must be made explicit before they can be tested.
-3. **Classify each specification** — tag each spec as functional, non-functional (performance, security, accessibility), or constraint (business rule, regulatory), because different spec types require different testing strategies and tools.
-4. **Identify specification gaps** — flag requirements that are ambiguous, contradictory, or untestable, and generate clarifying questions, because building against incomplete specs guarantees rework.
-5. **Generate test skeletons from specs** — create one test case per specification with the assertion structure defined but implementation left empty, because writing tests first forces the specification to be concrete and verifiable.
-6. **Map specs to implementation boundaries** — identify which modules, functions, or endpoints each specification maps to, because knowing where the spec should be satisfied guides both implementation and test placement.
-7. **Implement against the spec** — write code to make each test pass, one specification at a time, because incremental implementation against explicit specs prevents scope creep and ensures every requirement is addressed.
-8. **Verify implementation coverage** — run the full test suite and map passing tests back to specifications, identifying any spec without a passing test, because code coverage measures lines executed while spec coverage measures requirements satisfied.
-9. **Check for specification drift** — compare the current implementation behavior against the original specs to detect features that have diverged from requirements, because drift accumulates silently and creates a gap between what the system does and what stakeholders expect.
-10. **Build the traceability matrix** — create a mapping from each requirement to its specifications, tests, and implementing code, because traceability is required for compliance audits and is valuable for impact analysis when requirements change.
-11. **Validate non-functional specs** — verify performance thresholds, security requirements, and accessibility standards with appropriate tooling (k6, OWASP ZAP, axe), because functional tests alone do not prove the system meets quality attributes.
-12. **Iterate on spec changes** — when requirements change, update the specification first, then update the tests, then update the implementation, because changing code without updating specs breaks traceability and hides requirement drift.
-13. **Document coverage gaps** — maintain a living document of specifications that cannot be tested automatically and require manual verification, because some requirements (usability, aesthetic quality) resist automation but still need verification.
-14. **Use agents for complex workflows** — delegate specification mining to `agents/spec-miner.md` and implementation verification to `agents/verifier.md`, because specialized agents produce more thorough results than a single generalist pass.
-
-## Output Format
-
-When performing SADD, provide:
-
-1. **Specification registry** — numbered list of every extracted spec in GIVEN-WHEN-THEN format with classification tags
-2. **Gap analysis** — list of ambiguous, contradictory, or untestable requirements with clarifying questions
-3. **Test plan** — test skeletons mapped to specifications, grouped by module or feature
-4. **Traceability matrix** — table mapping requirement ID to spec ID to test ID to implementing code
-5. **Coverage report** — percentage of specs with passing tests, with explicit list of uncovered specs
-
-## References
-
-| File | Purpose |
-|------|---------|
-| `references/spec-mining.md` | Techniques for extracting testable specifications from natural language requirements |
-| `references/test-generation.md` | Patterns for generating test cases from specifications across frameworks |
-| `references/verification.md` | Strategies for verifying implementation against specifications and detecting drift |
-| `references/coverage-mapping.md` | Building and maintaining traceability matrices and spec coverage reports |
-| `agents/spec-miner.md` | Agent that extracts structured specifications from requirements documents |
-| `agents/verifier.md` | Agent that validates implementation against extracted specifications |

package/workflows/skills/sadd/agents/spec-miner.md

@@ -1,52 +0,0 @@
-# Spec-Miner Agent
-
-## Role
-
-You are a specification mining agent. Your job is to extract implicit behavioral specifications from existing codebases, test suites, API contracts, and documentation when formal specifications do not exist.
-
-## When to Invoke
-
-- A legacy codebase needs rewriting but has no formal specification document.
-- An API has consumers but the behavioral contract is undocumented.
-- A refactoring effort requires a behavioral baseline to prevent regressions.
-- An inherited project needs specification documentation for new team members.
-
-## Operating Procedure
-
-1. **Identify mining sources.** Catalog the available evidence: test files, code contracts (assertions, guards, type signatures), inline comments, commit history, API documentation, and consumer usage patterns. Rank them by reliability (tests > code contracts > comments > commit messages).
-
-2. **Extract behavioral specifications from tests.** For each test, derive the requirement it implicitly validates. Use the test name, setup, assertion, and teardown to reconstruct the expected behavior. Output as: "The system MUST [behavior] WHEN [condition]."
-
-3. **Extract specifications from code contracts.** Scan for validation logic (input guards, type checks, range constraints), error handling (catch blocks, error codes), and invariants (assertions, preconditions). Each contract point becomes a specification clause.
-
-4. **Extract specifications from comments and documentation.** Look for NOTE, HACK, FIXME, and TODO annotations. Notes and hacks often encode undocumented requirements. TODOs represent future work and should be flagged but not included as current specifications.
-
-5. **Deduplicate and reconcile.** Merge specifications that describe the same behavior from different sources. Flag contradictions (e.g., a test expects X but a comment says Y) for human resolution.
-
-6. **Assign unique identifiers.** Every mined specification gets a REQ-XXX ID, a source reference, and a confidence level (high = from passing test, medium = from code contract, low = from comment only).
-
-7. **Produce the specification document.** Output a structured requirements registry with ID, requirement text, source, confidence, and type.
-
-## Output Format
-
-```markdown
-## Mined Specifications
-
-| REQ ID | Requirement | Source | Confidence | Type |
-|--------|------------|--------|------------|------|
-| REQ-001 | The system MUST [behavior] WHEN [condition] | test_name / code:line / comment | High/Medium/Low | Functional/Non-Functional |
-
-## Contradictions
-| # | Source A | Source B | Conflict Description |
-|---|---------|---------|---------------------|
-
-## Unmined Areas
-- [Areas of the codebase not covered by this mining pass]
-```
-
-## Constraints
-
-- Never invent specifications that are not evidenced by code, tests, or documentation.
-- Always flag low-confidence specifications for human review.
-- Never include TODO items as current requirements.
-- Always cite the exact source (file, line, test name) for every mined specification.

package/workflows/skills/sadd/agents/verifier.md

@@ -1,70 +0,0 @@
-# Verifier Agent
-
-## Role
-
-You are a specification verifier agent. Your job is to cross-reference a completed implementation against a specification (formal or mined) and produce a verification report that identifies covered requirements, gaps, failures, and ambiguities.
-
-## When to Invoke
-
-- An implementation is complete and needs verification against its specification.
-- A pull request needs review for specification compliance.
-- A release candidate requires a compliance check before deployment.
-- A rewrite needs confirmation that it preserves all behaviors of the original.
-
-## Operating Procedure
-
-1. **Load the specification.** Read the requirements registry or traceability matrix. Confirm the total number of requirements and their IDs. If no matrix exists, flag this and recommend running the spec-miner agent first.
-
-2. **Locate tests for each requirement.** For every REQ-XXX, find the corresponding TEST-XXX. Check that the test exists, is not skipped, and asserts the requirement's expected behavior. Flag requirements without tests.
-
-3. **Run or review test results.** If test results are available, check pass/fail status for each requirement's tests. If results are unavailable, analyze the test code for correctness of assertions relative to the requirement text.
-
-4. **Locate implementation for each requirement.** For every REQ-XXX, find the code location that implements the specified behavior. Verify that the implementation logic matches the requirement semantics, not just the test expectations.
-
-5. **Check for behavioral mismatches.** Compare the requirement text against the implementation logic. Look for:
-   - Off-by-one errors in boundaries (e.g., "at least 8" implemented as `> 8` instead of `>= 8`).
-   - Missing error handling for specified error cases.
-   - Hardcoded values that differ from the specification.
-   - Partial implementations that handle the happy path but skip edge cases.
-
-6. **Identify untested code paths.** Look for implementation branches (if/else, switch/case, try/catch) that have no corresponding test. These represent potential specification gaps or undertested requirements.
-
-7. **Produce the verification report.** Output a structured report with coverage summary, failures, gaps, and recommendations.
-
-## Output Format
-
-```markdown
-## Verification Report
-
-### Coverage Summary
-| Metric | Count |
-|--------|-------|
-| Total requirements | N |
-| Requirements with passing tests | X |
-| Requirements with failing tests | Y |
-| Requirements with no test | Z |
-| Requirements with no implementation | W |
-
-### Failures
-| REQ ID | Test ID | Expected | Actual | Root Cause |
-|--------|---------|----------|--------|------------|
-
-### Gaps
-| REQ ID | Gap Type | Description | Recommendation |
-|--------|----------|-------------|----------------|
-
-### Behavioral Mismatches
-| REQ ID | Spec Says | Code Does | Severity |
-|--------|-----------|-----------|----------|
-
-### Verdict
-[PASS / PASS_WITH_WARNINGS / FAIL]
-[Summary of what needs to happen before this implementation can ship.]
-```
-
-## Constraints
-
-- Never mark a requirement as "verified" without evidence (passing test + matching implementation).
-- Always flag skipped tests as gaps, even if the skip reason seems valid.
-- Never assume implementation correctness from test passage alone; verify the test actually asserts the specified behavior.
-- Always provide a clear verdict with actionable next steps.

package/workflows/skills/sadd/evals/assertions.md

@@ -1,50 +0,0 @@
-# SADD Eval Assertions
-
-## Eval 1: Spec Extraction from Requirements
-
-This eval tests whether the skill can mine structured, testable specifications from a natural language requirements document.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                          |
-|---|----------|-------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| 1 | contains | `GIVEN` — GIVEN-WHEN-THEN format usage           | The structured format makes specs testable. Free-form specs cannot be directly mapped to test cases.    |
-| 2 | contains | `unique` — Email uniqueness constraint            | This is a data integrity constraint that requires database-level enforcement and a specific test.       |
-| 3 | contains | `24 hours` — Time-bound expiry spec              | Time-bound requirements are frequently missed in spec extraction and require explicit test setup.       |
-| 4 | contains | `rate limit` — Rate limiting as non-functional   | The 3-per-hour limit is a non-functional requirement that needs its own test with time manipulation.    |
-| 5 | contains | `unverified` — Access restriction spec            | Security specs must be extracted separately because they require negative testing (denied access).      |
-
-### What a passing response looks like
-
-- 7+ specifications extracted (one per bullet in the requirements, plus implicit edge cases).
-- Each spec has a unique ID (e.g., SPEC-001, SPEC-002).
-- Each spec uses GIVEN-WHEN-THEN format with concrete conditions.
-- Specs are classified as functional, non-functional, or security.
-- At least one gap is identified (e.g., "What happens when an expired link is clicked?").
-- Ambiguous requirements are flagged with clarifying questions.
-
----
-
-## Eval 2: Verification Workflow
-
-This eval tests whether the skill can systematically verify an implementation against specifications and identify gaps.
-
-### Assertions
-
-| # | Type     | What it checks                                  | Why it matters                                                                                          |
-|---|----------|-------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| 1 | contains | `SPEC-003` — Identifies missing quantity-to-zero | The Cart class has no method to set quantity. This gap must be explicitly identified.                   |
-| 2 | contains | `SPEC-005` — Identifies missing checkout guard   | There is no checkout method at all. This is a complete implementation gap.                              |
-| 3 | contains | `SPEC-001` — Confirms add item works             | The addItem method correctly increments itemCount. Must confirm satisfied specs, not only gaps.         |
-| 4 | contains | `SPEC-004` — Confirms duplicate handling          | The existing item check in addItem satisfies the deduplication spec. Must verify positive cases too.   |
-| 5 | contains | `gap` — Explicit gap identification              | Must clearly label gaps and recommend specific implementation changes, not just note them.              |
-
-### What a passing response looks like
-
-- A specification-by-specification verification report.
-- SPEC-001 and SPEC-002 marked as satisfied with evidence from the code.
-- SPEC-004 marked as satisfied, pointing to the `existing` item check.
-- SPEC-003 marked as NOT satisfied, with recommendation to add `setQuantity` or `updateQuantity` method.
-- SPEC-005 marked as NOT satisfied, with recommendation to add `checkout` method with empty cart validation.
-- A summary table showing 3/5 specs satisfied (60% spec coverage).
-- Suggested test cases for the two missing implementations.

package/workflows/skills/sadd/evals/evals.json

@@ -1,66 +0,0 @@
-[
-  {
-    "name": "spec-extraction-from-requirements",
-    "description": "Validate that the skill extracts complete, testable specifications from a natural language requirements document using structured formats.",
-    "input": "Extract testable specifications from this requirements document:\n\n## User Registration\n- Users must register with email and password.\n- Email must be unique across the system.\n- Password must be at least 8 characters with one uppercase, one lowercase, and one number.\n- After registration, a verification email is sent.\n- Unverified accounts cannot access protected resources.\n- Verification links expire after 24 hours.\n- Users can request a new verification email, but not more than 3 times per hour.\n\nProvide specifications in GIVEN-WHEN-THEN format with IDs and classification.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "GIVEN",
-        "description": "Must use the GIVEN-WHEN-THEN format for specifications, as this is the standard format for testable behavioral specs."
-      },
-      {
-        "type": "contains",
-        "value": "unique",
-        "description": "Must extract the email uniqueness constraint as a distinct specification, since it requires a specific database-level check."
-      },
-      {
-        "type": "contains",
-        "value": "24 hours",
-        "description": "Must extract the verification link expiry as a testable time-bound specification, not just a narrative description."
-      },
-      {
-        "type": "contains",
-        "value": "rate limit",
-        "description": "Must extract the 3-per-hour rate limit on verification email requests as a non-functional specification."
-      },
-      {
-        "type": "contains",
-        "value": "unverified",
-        "description": "Must extract the access restriction on unverified accounts as a security specification with explicit test criteria."
-      }
-    ]
-  },
-  {
-    "name": "verification-workflow",
-    "description": "Validate that the skill can verify an implementation against specifications and identify gaps.",
-    "input": "I have these specifications for a shopping cart:\n\nSPEC-001: GIVEN a logged-in user WHEN they add an item to the cart THEN the cart item count increases by 1.\nSPEC-002: GIVEN a cart with items WHEN the user removes an item THEN the cart item count decreases by 1.\nSPEC-003: GIVEN a cart with items WHEN the user changes quantity to 0 THEN the item is removed from the cart.\nSPEC-004: GIVEN a cart WHEN the user adds an item already in the cart THEN the quantity increases instead of adding a duplicate.\nSPEC-005: GIVEN an empty cart WHEN the user proceeds to checkout THEN they see an error message.\n\nHere is the implementation:\n\n```javascript\nclass Cart {\n  constructor() { this.items = []; }\n\n  addItem(product, quantity = 1) {\n    const existing = this.items.find(i => i.product.id === product.id);\n    if (existing) { existing.quantity += quantity; }\n    else { this.items.push({ product, quantity }); }\n  }\n\n  removeItem(productId) {\n    this.items = this.items.filter(i => i.product.id !== productId);\n  }\n\n  get itemCount() {\n    return this.items.reduce((sum, i) => sum + i.quantity, 0);\n  }\n}\n```\n\nVerify the implementation against the specifications. Identify which specs are satisfied and which have gaps.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "SPEC-003",
-        "description": "Must identify SPEC-003 as not satisfied because there is no setQuantity method that handles setting quantity to 0."
-      },
-      {
-        "type": "contains",
-        "value": "SPEC-005",
-        "description": "Must identify SPEC-005 as not satisfied because there is no checkout method that validates cart emptiness."
-      },
-      {
-        "type": "contains",
-        "value": "SPEC-001",
-        "description": "Must confirm SPEC-001 is satisfied by the addItem method with quantity tracking."
-      },
-      {
-        "type": "contains",
-        "value": "SPEC-004",
-        "description": "Must confirm SPEC-004 is satisfied by the existing item check in addItem that increments quantity."
-      },
-      {
-        "type": "contains",
-        "value": "gap",
-        "description": "Must explicitly identify specification gaps and recommend implementation changes to close them."
-      }
-    ]
-  }
-]

package/workflows/skills/sadd/examples/01-basic-usage.md

@@ -1,72 +0,0 @@
-# Example: Extracting Requirements from Acceptance Criteria
-
-## Context
-
-A product manager has written acceptance criteria for a password reset feature. The developer needs to extract testable requirements and build a traceability matrix before writing any code.
-
-## User Prompt
-
-> Here are the acceptance criteria for our password reset feature: (1) User clicks "Forgot Password" and enters their email. (2) System sends a reset link valid for 1 hour. (3) Link contains a unique token. (4) User sets a new password that must be at least 8 characters with one number. (5) After reset, all existing sessions are invalidated. Extract requirements and create a test plan.
-
-## Skill Response
-
-### Specification Source
-
-- **Type:** Semi-formal (acceptance criteria)
-- **Location:** Product brief, Sprint 12
-- **Version:** v1.0 (initial)
-
-### Requirements Registry
-
-| REQ ID | Requirement Text | Type | Priority |
-|--------|-----------------|------|----------|
-| REQ-001 | System sends a password reset email when user submits a registered email address | Functional | Must |
-| REQ-002 | Reset link expires after 1 hour from generation | Functional | Must |
-| REQ-003 | Reset link contains a cryptographically unique token | Functional | Must |
-| REQ-004 | New password must be at least 8 characters | Functional | Must |
-| REQ-005 | New password must contain at least one numeric character | Functional | Must |
-| REQ-006 | All existing sessions are invalidated after successful password reset | Functional | Must |
-| REQ-007 | System does not reveal whether an email is registered (security) | Non-Functional | Should |
-| REQ-008 | Reset token is single-use (cannot be reused after successful reset) | Functional | Should |
-
-### Specification Gaps Identified
-
-| # | Gap Description | Decision Made | Test Added |
-|---|----------------|---------------|------------|
-| 1 | What happens if email is not registered? Spec says "enters their email" but not what happens for unknown emails. | Show same success message for registered and unregistered emails to prevent email enumeration. | TEST-007 |
-| 2 | Can a reset token be used more than once? Spec does not mention single-use. | Token should be single-use and invalidated after successful reset. | TEST-008 |
-| 3 | Rate limiting on reset requests not specified. | Limit to 3 reset requests per email per hour. | TEST-009 |
-
-### Test Cases
-
-| TEST ID | REQ ID | Test Description | Type |
-|---------|--------|-----------------|------|
-| TEST-001 | REQ-001 | Submit registered email; verify reset email is sent | Positive |
-| TEST-002 | REQ-002 | Use reset link after 61 minutes; verify it is rejected | Negative/Boundary |
-| TEST-003 | REQ-002 | Use reset link at 59 minutes; verify it works | Positive/Boundary |
-| TEST-004 | REQ-003 | Generate two reset tokens; verify they are different | Positive |
-| TEST-005 | REQ-004 | Submit 7-character password; verify rejection | Negative |
-| TEST-006 | REQ-005 | Submit all-letter password; verify rejection | Negative |
-| TEST-007 | REQ-007 | Submit unregistered email; verify same response as registered | Security |
-| TEST-008 | REQ-008 | Use reset token twice; verify second use is rejected | Negative |
-| TEST-009 | GAP-003 | Submit 4 reset requests in 1 hour; verify 4th is rate-limited | Negative |
-| TEST-010 | REQ-006 | Reset password; verify existing session tokens are invalidated | Positive |
-
-### Traceability Matrix
-
-| REQ ID | Test IDs | Implementation | Status |
-|--------|----------|---------------|--------|
-| REQ-001 | TEST-001 | Pending | Not started |
-| REQ-002 | TEST-002, TEST-003 | Pending | Not started |
-| REQ-003 | TEST-004 | Pending | Not started |
-| REQ-004 | TEST-005 | Pending | Not started |
-| REQ-005 | TEST-006 | Pending | Not started |
-| REQ-006 | TEST-010 | Pending | Not started |
-| REQ-007 | TEST-007 | Pending | Not started |
-| REQ-008 | TEST-008 | Pending | Not started |
-
-### Key Decisions
-
-1. **Mined 8 requirements from 5 acceptance criteria** -- The original 5 criteria contained compound statements. Splitting them into atomic requirements (REQ-004 and REQ-005 from a single criterion) ensures each is independently testable.
-2. **Added 3 specification gaps** -- Security-critical features like password reset commonly under-specify error handling and abuse prevention. Documenting gaps upfront prevents them from becoming production incidents.
-3. **Boundary tests for time-based requirements** -- REQ-002 gets both a 59-minute (should work) and 61-minute (should fail) test to verify the exact boundary.

package/workflows/skills/sadd/examples/01-spec-extraction.md

@@ -1,92 +0,0 @@
-# Example: Extract Specifications from a Feature Requirements Document
-
-## Scenario
-
-A product manager wrote a feature requirements document for a file upload feature. The development team needs to extract testable specifications before implementation begins.
-
-## User Prompt
-
-> Extract testable specifications from this feature requirement:
->
-> ## File Upload Feature
-> Users should be able to upload files to their project workspace. Supported formats are PDF, PNG, JPG, and SVG. Maximum file size is 10MB. Files are stored in S3 with a unique key. Uploaded files appear in the file list immediately. Users can delete their own files but not files uploaded by others. Administrators can delete any file. File names are sanitized to remove special characters.
-
-## Expected Response
-
-### Specification Registry
-
-| ID       | Classification | Specification |
-|----------|---------------|---------------|
-| SPEC-001 | Functional    | GIVEN a logged-in user WHEN they upload a PDF, PNG, JPG, or SVG file under 10MB THEN the file is stored successfully and a confirmation is returned. |
-| SPEC-002 | Constraint    | GIVEN a user attempting to upload WHEN the file format is not PDF, PNG, JPG, or SVG THEN the upload is rejected with a descriptive error message. |
-| SPEC-003 | Constraint    | GIVEN a user attempting to upload WHEN the file size exceeds 10MB THEN the upload is rejected with a file-too-large error. |
-| SPEC-004 | Functional    | GIVEN a successful upload WHEN the file is stored THEN it is placed in S3 with a unique key that prevents collisions. |
-| SPEC-005 | Functional    | GIVEN a successful upload WHEN the user views the file list THEN the newly uploaded file appears without requiring a page refresh. |
-| SPEC-006 | Security      | GIVEN a non-admin user WHEN they attempt to delete a file uploaded by another user THEN the deletion is denied with a 403 status. |
-| SPEC-007 | Security      | GIVEN an admin user WHEN they attempt to delete any file THEN the deletion succeeds regardless of who uploaded it. |
-| SPEC-008 | Functional    | GIVEN a user who uploaded a file WHEN they delete it THEN the file is removed from both S3 and the file list. |
-| SPEC-009 | Functional    | GIVEN a file with special characters in its name WHEN it is uploaded THEN the file name is sanitized to contain only alphanumeric characters, hyphens, underscores, and the original extension. |
-
-### Gap Analysis
-
-| Issue | Requirement Text | Question |
-|-------|-----------------|----------|
-| Ambiguous | "appear immediately" | Does "immediately" mean optimistic UI update, or server-confirmed? What is the acceptable latency? |
-| Missing | File name sanitization | What happens if two files have the same name after sanitization? Is a suffix added? |
-| Missing | Upload limits | Is there a limit on the number of files per project or per user? |
-| Missing | Concurrent uploads | Can multiple users upload to the same project simultaneously? |
-| Missing | File replacement | Can a user upload a file with the same name as an existing file? Does it overwrite or create a new version? |
-
-### Test Plan (Skeletons)
-
-```javascript
-describe('File Upload', () => {
-  test('SPEC-001: accepts valid file formats under size limit', async () => {
-    // Arrange: create a 5MB PDF file
-    // Act: POST /api/files with the file
-    // Assert: 201 status, file ID returned, file exists in S3
-  });
-
-  test('SPEC-002: rejects unsupported file formats', async () => {
-    // Arrange: create a .exe file
-    // Act: POST /api/files with the file
-    // Assert: 400 status, error message mentions supported formats
-  });
-
-  test('SPEC-003: rejects files exceeding size limit', async () => {
-    // Arrange: create an 11MB PNG file
-    // Act: POST /api/files with the file
-    // Assert: 413 status, error message mentions 10MB limit
-  });
-
-  test('SPEC-006: prevents non-owner from deleting files', async () => {
-    // Arrange: user A uploads a file, authenticate as user B
-    // Act: DELETE /api/files/:id as user B
-    // Assert: 403 status, file still exists
-  });
-
-  test('SPEC-007: allows admin to delete any file', async () => {
-    // Arrange: user A uploads a file, authenticate as admin
-    // Act: DELETE /api/files/:id as admin
-    // Assert: 200 status, file removed from S3 and database
-  });
-});
-```
-
-### Traceability Matrix
-
-| Requirement | Spec IDs | Test IDs | Module |
-|-------------|----------|----------|--------|
-| Format validation | SPEC-001, SPEC-002 | TEST-001, TEST-002 | upload-service |
-| Size limit | SPEC-003 | TEST-003 | upload-service |
-| S3 storage | SPEC-004 | TEST-004 | storage-adapter |
-| Real-time display | SPEC-005 | TEST-005 | file-list-component |
-| Delete authorization | SPEC-006, SPEC-007, SPEC-008 | TEST-006, TEST-007, TEST-008 | file-service |
-| Name sanitization | SPEC-009 | TEST-009 | upload-service |
-
-## Why This Response Works
-
-- Extracts 9 specifications from 8 sentences of requirements, showing that each sentence may contain multiple testable conditions.
-- Identifies 5 specification gaps that would have been discovered only during implementation without SADD.
-- Provides test skeletons that can be implemented immediately without further spec interpretation.
-- The traceability matrix enables impact analysis when requirements change.