@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/references/pr-description-patterns.md

@@ -1,215 +0,0 @@
-# PR Description Patterns
-
-## Overview
-
-A well-written PR description is the single highest-leverage action for getting fast, high-quality reviews. Reviewers who understand the context, motivation, and risks of a change provide better feedback in fewer cycles. This reference provides templates and patterns for different change types.
-
-## Universal Structure
-
-Every PR description should contain these sections, regardless of change type:
-
-### Title
-
-- Imperative mood: "Add search endpoint" not "Added search endpoint"
-- Under 72 characters
-- Prefix with type if the project uses conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`
-
-### What / Why / How
-
-- **What**: One sentence describing the change at a high level.
-- **Why**: The motivation — what problem this solves, what user need it addresses, what issue it closes.
-- **How**: The approach taken, key design decisions, and any alternatives considered.
-
-### Testing
-
-- What was tested (unit, integration, E2E, manual).
-- How it was tested (specific commands, test scenarios).
-- What was not tested and why.
-
-### Risk Assessment
-
-- Areas of highest risk or uncertainty.
-- Rollback strategy if something goes wrong.
-- Dependencies on other changes or deployments.
-
-## Pattern: Feature Addition
-
-```markdown
-## What
-Add [feature] to [area] for [user type].
-
-## Why
-[Problem statement]. Currently [current behavior]. Users need [desired behavior].
-Closes #[issue].
-
-## How
-- [Key implementation decision 1]
-- [Key implementation decision 2]
-- [New dependency, if any, and why]
-
-## Testing
-- Unit tests: [what is covered]
-- Integration tests: [what is covered]
-- Manual testing: [scenarios tested]
-- Not tested: [gaps and why]
-
-## Screenshots
-[Before/after for UI changes]
-
-## Review Focus
-- [Specific area needing attention]
-- [Architecture question, if any]
-```
-
-## Pattern: Bug Fix
-
-```markdown
-## What
-Fix [bug description] in [area].
-
-## Root Cause
-[Explanation of why the bug occurred — not just what the fix is, but what was wrong.]
-
-## Fix
-[Description of the fix and why this approach was chosen over alternatives.]
-
-## How to Reproduce (Before Fix)
-1. [Step 1]
-2. [Step 2]
-3. [Observe: incorrect behavior]
-
-## Verification (After Fix)
-1. [Step 1]
-2. [Step 2]
-3. [Observe: correct behavior]
-
-## Testing
-- [Regression test added to prevent recurrence]
-- [Related edge cases checked]
-
-## Risk
-- [Could this fix break other behavior?]
-- [Is this a symptom fix or root cause fix?]
-```
-
-## Pattern: Refactoring
-
-```markdown
-## What
-Refactor [area] from [old approach] to [new approach].
-
-## Why
-[Specific problems with the current approach: performance, maintainability, scalability.]
-No behavior change — this is a pure refactor.
-
-## Approach
-[How the refactoring was done, what the new structure looks like.]
-
-## Verification
-- All existing tests pass without modification (confirms no behavior change).
-- [Additional verification, if any.]
-
-## Commit Strategy
-Review commit-by-commit:
-1. [First commit: preparatory changes]
-2. [Second commit: core refactoring]
-3. [Third commit: cleanup and tests]
-
-## Risk
-- [Areas where behavior change might have been accidentally introduced]
-- [Performance implications, if any]
-```
-
-## Pattern: Database Migration
-
-```markdown
-## What
-[Migration description: add table, add column, change index, etc.]
-
-## Why
-[What feature or fix requires this schema change.]
-
-## Migration Details
-- **Backward compatible**: [Yes/No — can the old code run with the new schema?]
-- **Estimated runtime**: [For large tables, how long will the migration take?]
-- **Locking behavior**: [Does this lock tables? For how long?]
-- **Rollback migration**: [Does a down migration exist? Has it been tested?]
-
-## Deployment Order
-1. [Deploy migration]
-2. [Deploy application code]
-3. [Or: deploy code first, then migration — explain order dependency]
-
-## Testing
-- Migration tested on a copy of production data (size: [X] rows).
-- Rollback migration tested.
-
-## Risk
-- [Data loss scenarios]
-- [Performance impact during migration]
-```
-
-## Pattern: Security Fix
-
-```markdown
-## What
-Fix [vulnerability type] in [area].
-
-## Severity
-[Critical / High / Medium / Low] — [brief justification].
-
-## Vulnerability Details
-[Description of the vulnerability — enough for reviewers to understand the threat model, but be mindful of disclosure if the repo is public.]
-
-## Fix
-[What the fix does and why this approach was chosen.]
-
-## Verification
-- [How the fix was verified — including attempting the exploit after the fix]
-- [Regression test added]
-
-## Urgency
-[Ship timeline — same day, this sprint, etc.]
-[Disclosure timeline — is there an external reporter waiting?]
-
-## Review Focus
-- Security completeness: does the fix address the root cause or just one vector?
-- Regression risk: could the fix break existing functionality?
-```
-
-## Anti-Patterns to Avoid
-
-### The empty description
-
-> "Fixed stuff"
-
-This tells reviewers nothing. Even a one-line change deserves a one-sentence explanation.
-
-### The novel
-
-A 2,000-word description for a 10-line change. Match description length to change complexity.
-
-### The copy-paste Jira ticket
-
-Pasting the entire Jira description is not a PR description. The PR should describe the implementation, not repeat the requirements.
-
-### The missing "why"
-
-> "Changed the timeout from 30s to 60s"
-
-Why? Was there a timeout error? A specific user report? A load test result? The "why" is what makes the change reviewable.
-
-### The optimistic "no risk"
-
-Every change has risk. Claiming "no risk" signals that the author has not thought about failure modes.
-
-## Checklist Before Submitting
-
-- [ ] Title is concise, imperative mood, under 72 characters
-- [ ] Description explains what, why, and how
-- [ ] Related issues are linked with closing keywords
-- [ ] Testing approach is described, including gaps
-- [ ] Risk areas are identified and explained
-- [ ] Screenshots included for UI changes
-- [ ] Review guidance specifies focus areas and expected depth
-- [ ] Draft/ready-for-review status is set correctly

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/requesting-code-review/references/reviewer-selection.md

@@ -1,162 +0,0 @@
-# Reviewer Selection
-
-## Overview
-
-Selecting the right reviewers is as important as writing good code. The wrong reviewer wastes time — theirs and yours. The right reviewer catches issues you cannot see, provides feedback you can act on, and approves with confidence. This reference covers how to choose reviewers based on change characteristics, team composition, and practical constraints.
-
-## Selection Criteria
-
-### Domain Expertise
-
-The most important factor. A reviewer who understands the domain can evaluate correctness, design, and edge cases that a generalist would miss.
-
-| Change Area              | Look for Reviewer With                        |
-|--------------------------|-----------------------------------------------|
-| Authentication / Auth    | Security expertise, auth protocol knowledge   |
-| Database / Migrations    | DBA knowledge, schema design experience       |
-| Payment / Billing        | Financial systems experience, compliance awareness |
-| Frontend / UI            | Component architecture, accessibility knowledge |
-| Infrastructure / DevOps  | Deployment, scaling, observability experience  |
-| API Design               | REST/GraphQL conventions, versioning experience|
-| Performance              | Profiling experience, system design knowledge  |
-
-### Recent Context
-
-A reviewer who recently worked on the affected code has a mental model that makes review faster and more thorough. Check `git log` for recent authors of the files you changed.
-
-**How to find context holders**:
-- `git log --format='%an' -- path/to/file | sort | uniq -c | sort -rn` — most frequent authors
-- `git log --since='3 months ago' --format='%an' -- path/to/file | head -5` — recent authors
-- CODEOWNERS file — designated owners per path
-
-### Availability and Workload
-
-A qualified reviewer who is overloaded will delay your review or give it less attention. Consider:
-
-- Current sprint workload and deadline pressure
-- Number of PRs already in their review queue
-- Time zone overlap for async review
-- PTO or meeting-heavy days
-
-**Practical rule**: If your first-choice reviewer has more than 3 pending reviews, assign someone else or explicitly negotiate timeline.
-
-### Author Experience Level
-
-Match reviewer seniority to the change risk:
-
-| Author Level  | Change Risk | Recommended Reviewer         |
-|---------------|-------------|------------------------------|
-| Junior        | High risk   | Senior + domain expert       |
-| Junior        | Low risk    | Mid-level peer               |
-| Mid-level     | High risk   | Senior or domain expert      |
-| Mid-level     | Low risk    | Any qualified peer           |
-| Senior        | High risk   | Another senior or principal  |
-| Senior        | Low risk    | Any qualified peer           |
-
-## How Many Reviewers
-
-### One reviewer (default)
-
-- Standard feature work, bug fixes, refactoring
-- The change is in a well-understood area
-- The author is experienced with the codebase
-
-### Two reviewers
-
-- The change spans multiple domains (backend + frontend, API + database)
-- The change touches security-sensitive areas
-- The change is high-risk and benefits from independent perspectives
-
-### Three or more reviewers (rare)
-
-- Architecture changes affecting the entire system
-- Public API changes with external consumers
-- Compliance-sensitive changes requiring multiple sign-offs
-
-**Warning**: More than 2 reviewers often causes diffusion of responsibility. Everyone assumes someone else will do the deep review. If you need 3+ reviewers, assign specific focus areas to each.
-
-## Assigning Focus Areas
-
-When using multiple reviewers, prevent duplicate effort by assigning focus areas:
-
-```
-@alice — Please review the database migration and query changes.
-         Focus on: index performance, backward compatibility, rollback safety.
-
-@bob   — Please review the API endpoint and request validation.
-         Focus on: input validation, error handling, API contract consistency.
-```
-
-This pattern:
-- Prevents reviewers from duplicating each other's effort
-- Ensures every area gets reviewed by the most qualified person
-- Makes the review request feel manageable rather than overwhelming
-
-## CODEOWNERS Integration
-
-If your repository uses a CODEOWNERS file, GitHub automatically suggests reviewers based on file paths. Use CODEOWNERS as a starting point, but override when:
-
-- The CODEOWNER is on PTO or overloaded
-- The change requires expertise the CODEOWNER does not have
-- The CODEOWNER is a team alias and you need a specific individual
-
-## When to Skip Review
-
-Some changes do not need full review:
-
-- **Automated dependency bumps** (Dependabot, Renovate) — review the changelog, not the lock file
-- **Generated code** (protobuf, OpenAPI, GraphQL codegen) — review the source schema, not the output
-- **Trivial fixes** — typo in a comment, fixing a broken link in docs
-
-Even skip-review changes should go through CI and get a quick approval from someone for audit trail purposes.
-
-## Communicating with Reviewers
-
-### When requesting
-
-- Tag the reviewer directly (not just assign in the UI)
-- State the urgency and desired timeline
-- Explain why you chose them specifically
-- Specify the focus area and review depth
-
-### Template for review request message
-
-```
-@reviewer I'd appreciate your review on this PR.
-
-Focus: [specific area or concern]
-Urgency: [blocking/normal/low priority]
-Depth: [quick sanity check / standard / deep review]
-Timeline: [ideally by when]
-
-Key context: [one sentence about what this change does and why]
-```
-
-### When your reviewer is slow
-
-1. Wait 24 hours (they may be busy)
-2. Send a polite ping: "Hey, just checking if you've had a chance to look at PR #X"
-3. If still no response after 48 hours, reassign with a note: "Reassigning to unblock — happy to add you back for a second pass"
-4. Never escalate to management without first trying steps 1-3
-
-## Anti-Patterns
-
-### The rubber stamp
-
-Assigning a reviewer who will approve without reading. This defeats the purpose of review.
-
-### The bottleneck
-
-Assigning the same senior engineer to every PR. They become a bottleneck and burn out.
-
-### The punishment reviewer
-
-Assigning the strictest reviewer to someone you are frustrated with. Reviews should improve code, not punish people.
-
-### The crowd
-
-Assigning 5 reviewers hoping someone will look at it. Assign 1-2 with clear expectations instead.
-
-### The surprise assignment
-
-Assigning someone without context or warning. Always communicate why you chose them and what you need.

package/workflows/workflows/agent-environment-setup/platforms/copilot/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/workflows/agent-environment-setup/platforms/copilot/skills/rust-best-practices/evals/assertions.md

@@ -1,33 +0,0 @@
-# Rust Best Practices — Eval Assertions
-
-## Eval 1: Ownership Design (rust-ownership-design)
-
-This eval tests whether the skill correctly designs ownership hierarchies to avoid unnecessary cloning in a data pipeline.
-
-### Assertions
-
-1. **Move semantics between stages** — The response must pass owned data (e.g., `Vec<Record>`) between pipeline stages using moves rather than cloning the entire dataset. Move semantics are zero-cost in Rust and the pipeline's linear data flow naturally supports them.
-
-2. **Shared references for the lookup table** — The read-only lookup table must be accessed via `&self` or `&HashMap<K, V>` rather than being cloned per worker. Read-only shared access is the fundamental borrow checker use case.
-
-3. **Arc for cross-thread sharing** — When the transform stage uses multiple threads/tasks, the lookup table must be wrapped in `Arc<T>` (not `Arc<Mutex<T>>`) because it is read-only and `Arc` provides shared ownership without synchronization overhead for immutable data.
-
-4. **Borrowing for intermediate access** — Within each stage, the code must use borrowed references (`&str`, `&[u8]`, `&Record`) for read-only operations rather than taking ownership when ownership transfer is not needed. This avoids unnecessary moves of data that the stage only inspects.
-
-5. **Explicit ownership rationale** — The response must explain (via comments or prose) why each type is owned vs. borrowed. The skill's value is not just in the code but in teaching the ownership reasoning that informs future design decisions.
-
-## Eval 2: Async Service Implementation (rust-async-service)
-
-This eval tests whether the skill produces a well-structured async HTTP service with proper error handling and shutdown.
-
-### Assertions
-
-1. **Axum Router with extractors** — The response must use axum's `Router`, `Json` extractor for request parsing, and `State` for shared application state (database pool). Axum's extractor pattern is the idiomatic way to decompose HTTP requests in Rust.
-
-2. **Graceful shutdown** — The service must implement shutdown using `tokio::signal` to listen for SIGTERM or using `CancellationToken` from `tokio_util`. The server must drain in-flight requests before exiting rather than dropping connections.
-
-3. **thiserror for library errors, anyhow for main** — Error types in the service layer must use `#[derive(thiserror::Error)]` with named variants. The `main` function should use `anyhow::Result` because application entry points log errors rather than match on them.
-
-4. **sqlx connection pool via State** — The PostgreSQL connection pool must be created with `sqlx::PgPool` and shared with handlers through axum's `State` extractor. The pool must be initialized before the server starts and outlive all requests.
-
-5. **IntoResponse for error conversion** — The response must implement `IntoResponse` (or use axum's error handling mechanisms) to convert domain error types into HTTP responses with appropriate status codes and JSON bodies. Handlers must not manually construct HTTP error responses.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/rust-best-practices/evals/evals.json

@@ -1,54 +0,0 @@
-[
-  {
-    "id": "rust-ownership-design",
-    "prompt": "I'm building a data pipeline in Rust with three stages: parse raw bytes into structured records, transform records by enriching with metadata from a lookup table, and serialize to JSON output. Design the ownership hierarchy so that data flows through the pipeline without unnecessary cloning. The lookup table is read-only and shared across transform workers. Show the type signatures and explain the ownership decisions.",
-    "assertions": [
-      {
-        "type": "content",
-        "value": "passes owned data (Vec<Record> or similar) between pipeline stages using move semantics rather than cloning"
-      },
-      {
-        "type": "content",
-        "value": "uses &self or shared references for the read-only lookup table rather than cloning it per worker"
-      },
-      {
-        "type": "content",
-        "value": "uses Arc for sharing the lookup table across threads/tasks if concurrency is involved"
-      },
-      {
-        "type": "content",
-        "value": "uses borrowing (&str, &[u8]) for intermediate read-only access within each stage"
-      },
-      {
-        "type": "content",
-        "value": "explains the ownership rationale with comments or prose describing why each type is owned vs borrowed"
-      }
-    ]
-  },
-  {
-    "id": "rust-async-service",
-    "prompt": "Implement an async HTTP service in Rust using axum that has these requirements:\n1. Health check endpoint\n2. A POST endpoint that accepts JSON, validates it, processes it asynchronously, and returns a result\n3. Graceful shutdown on SIGTERM using tokio CancellationToken\n4. Structured error handling with thiserror for the library layer and anyhow for the binary\n5. Connection to a PostgreSQL database using sqlx with connection pooling\n\nTarget Rust 2024 edition.",
-    "assertions": [
-      {
-        "type": "content",
-        "value": "uses axum Router with handler functions and extractors (Json, State) for request handling"
-      },
-      {
-        "type": "content",
-        "value": "implements graceful shutdown using tokio CancellationToken or signal handling with tokio::signal"
-      },
-      {
-        "type": "content",
-        "value": "defines error types with #[derive(thiserror::Error)] for structured variants and uses anyhow::Result in main"
-      },
-      {
-        "type": "content",
-        "value": "uses sqlx::PgPool or equivalent connection pool passed via axum State or Extension"
-      },
-      {
-        "type": "content",
-        "value": "implements the IntoResponse trait or uses axum error handling to convert domain errors into appropriate HTTP responses"
-      }
-    ]
-  }
-]

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/sadd/SKILL.md

@@ -1,75 +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 |
-
-## Copilot Platform Notes
-
-- Custom agents are defined in `.github/agents/*.md` with YAML frontmatter: `name`, `description`, `tools`, `model`, `handoffs`.
-- Agent `handoffs` field enables guided workflow transitions (e.g., `@project-planner` → `@orchestrator`).
-- Skill files are stored under `.github/skills/` (skill markdown) and `.github/prompts/` (prompt files).
-- Path-scoped instructions in `.github/instructions/*.instructions.md` provide file-pattern-targeted guidance via `applyTo` frontmatter.
-- User arguments are provided as natural language input in the prompt, not through a `$ARGUMENTS` variable.
-- Frontmatter keys `context: fork` and `allowed-tools` are not natively supported; guidance is advisory.
-- Reference files can be included via `#file:references/<name>.md` syntax in Copilot Chat.
-- MCP configuration lives in `.vscode/mcp.json`. MCP skill tools are available when configured.
-- Rules file: `.github/copilot-instructions.md` — broad and stable, not task-specific.