@sallmarta/eye-hate-agent 1.0.0

package/docs/vibes/reusable-prompts/00-project-docs-parity.md

@@ -0,0 +1,88 @@
+# Project Docs Parity Reusable Prompt
+
+Read `docs/eyehateagent-contract.md` first.
+
+Audit the repository for **documentation-system drift**.
+
+## Goal
+
+Find mismatches where project docs, platform instruction surfaces (mirrored rule files), skills, reusable prompts, workflow docs, quick-reference material, or relevant implementation evidence disagree about the same fact.
+
+## Scope
+
+Check at least these areas when present:
+
+- `docs/project-docs/`
+- `docs/project-docs/index.md`
+- `docs/project-docs/technical-guidelines/`
+- relevant code, tests, configs, or runtime-facing artifacts when a finding depends on current implementation behavior or source-of-truth ownership
+- clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/`
+- platform instruction surfaces (mirrored rule files)
+- `docs/vibes/skills/`
+- `docs/vibes/reusable-prompts/`
+- workflow docs and handoff docs
+
+### High-Value Drift Categories
+
+- stack and dependency choices
+- test commands and quality gates
+- architecture and dependency rules
+- optional and conditional regular-doc inventory mismatches
+- API / integration ownership
+- technical guideline ownership, overlap, and missing guideline index coverage
+- semantic legacy-to-owner mapping mismatches where content is relevant but naming differs
+- code-vs-doc authority mismatches where current implementation and active docs disagree
+- workflow expectations
+- roadmap / phase naming
+- project identity and naming
+- undocumented domain knowledge embedded in the codebase (e.g., decision rationale in comments, architectural constraints in configs, domain rules in validation logic) that should be surfaced into project docs
+
+## Required Behavior
+
+1. Use project docs as the primary source of truth for documentation ownership and doc-to-doc drift unless the repository explicitly states otherwise.
+2. Treat `docs/eyehateagent-contract.md` as the ownership map.
+3. Treat `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` as the authoritative inventories for optional regular docs and guideline docs when present.
+4. Treat clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/` as migration input only, not as owner-doc paths.
+5. When evaluating legacy material, classify it by the durable concern it governs rather than by its legacy name or path. Treat names such as `epic`, `milestone`, `roadmap`, `protocol`, `procedure`, `policy`, or `standard` as hints only.
+6. Report likely mappings when content points to an active owner even if naming differs, such as phased-planning content that should map to `foundation/phases/` or technical-rule content that should map to `technical-guidelines/`.
+7. Distinguish between:
+   - true contradiction
+   - stale summary
+   - historical artifact
+   - optional module not currently active
+8. When a repo is migrating from another documentation format, use those reference folders to map legacy topics into the correct owner docs under `docs/project-docs/`.
+9. Treat a missing `docs/project-docs/index.md` as drift when optional or conditional regular docs exist beyond the always-required core set.
+10. Treat a missing `technical-guidelines/index.md` as drift when guideline files exist.
+11. Treat registry entries without matching files and files without matching registry entries as drift unless the registry explicitly marks them deprecated or archived.
+12. Treat a missing recommended guideline as drift only when the repo already claims that domain is covered or the repo claims to be fully documented for that domain.
+13. When a finding depends on whether the implementation or the documentation is authoritative, inspect the relevant code, tests, configs, or runtime-facing artifacts before classifying the issue.
+14. If code and documentation conflict and the repository does not explicitly declare which source is authoritative for that fact, do not assume. Report the conflict and ask the user for direction before recommending a fix path.
+15. If a legacy artifact could plausibly map to more than one active owner, or if preserving the legacy label may be intentional, ask the user for direction instead of silently classifying it.
+16. When asking for that direction, prefer a concise question that names the fact in conflict and the likely choices. Example: `I found a conflict between the code and the docs for the active API behavior. Should I treat 1. the code as correct and update the docs, 2. the docs as correct and treat the code as drift, or 3. mark this as an intentional temporary mismatch?`
+17. If strong repository evidence already establishes the authority order for that fact, state that evidence explicitly instead of asking.
+18. Treat missing code evidence the same as missing doc evidence: reduce confidence, state the limitation, and avoid guessing.
+19. Do not fix anything unless explicitly asked.
+
+## Output Contract
+
+For each finding, include:
+
+- severity
+- fact in conflict
+- source-of-truth file
+- conflicting file
+- whether the conflict is doc-vs-doc, code-vs-doc, or registry-vs-file
+- why it matters
+- recommended owner to update
+- whether user direction is required before deciding the fix path
+
+## Final Pass
+
+End with:
+
+1. a short list of highest-priority drift items
+2. a short list of acceptable historical artifacts that should not be treated as blockers
+
+## Inputs
+
+Use the current repository docs, platform instruction surfaces, skills, reusable prompts, and any relevant workflow or summary artifacts available below.

package/docs/vibes/reusable-prompts/00-project-docs-refresh.md

@@ -0,0 +1,81 @@
+# Project Docs Refresh Reusable Prompt
+
+Read `docs/eyehateagent-contract.md` first.
+
+Refresh the existing project documentation after a change in scope, stack, workflow, architecture, testing policy, or product behavior.
+
+## Goal
+
+Update **only the docs that own the changed information** while keeping the documentation set consistent.
+
+## Required Behavior
+
+1. Read the current project docs before editing anything.
+2. Use `docs/eyehateagent-contract.md` to identify which files own the changed information.
+3. Read `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` when present and treat them as the authoritative inventories for optional docs and guideline docs.
+4. When clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/` exist, read them as migration input only and do not treat them as owner-doc paths.
+5. Update only the affected docs and any documents that summarize them.
+6. Preserve stable headings wherever possible.
+7. Avoid rewriting unrelated sections.
+8. If the change introduces a new durable concern, create the smallest justified new doc.
+9. If the change affects an optional regular doc or its metadata, update `docs/project-docs/index.md` when present.
+10. If the change affects domain-specific technical guidance, update the owning guideline and `technical-guidelines/index.md` when present.
+11. When legacy or reference docs are being mapped into the active owner-doc set, classify them by the durable concern they govern rather than by the legacy folder or filename; legacy names are hints only.
+12. Normalize non-standard legacy labels by meaning when they map cleanly to an active owner. For example, `epic`, `milestone`, or `roadmap` material may map to `docs/project-docs/foundation/phases/`, while `protocol`, `procedure`, `policy`, or `standard` material may map to `docs/project-docs/technical-guidelines/` when the content is domain-specific technical guidance.
+13. When legacy or reference docs show that a justified optional doc should become active under `docs/project-docs/`, promote it into the active owner-doc set instead of leaving it stranded in reference-only folders.
+14. When legacy or reference docs contain domain-specific technical guidance that is still valid, create or update the relevant files under `docs/project-docs/technical-guidelines/` and create `technical-guidelines/index.md` when any guideline becomes active.
+15. When legacy or reference docs contain explicit phased planning, epic tracking, or execution-map detail that should stay active, create or update the relevant files under `docs/project-docs/foundation/phases/`, including `foundation/phases/index.md`, and register the active optional doc in `docs/project-docs/index.md`.
+16. If a legacy artifact could plausibly map to more than one active owner, or if preserving the legacy label may be intentional, ask the user for direction instead of guessing.
+17. Preserve valuable legacy sections (e.g., 'Decision Rationale') that do not exist in the starter templates. Decide whether this information belongs as a new custom section in an existing document or warrants a new separate file entirely. Ask the user if the best approach is ambiguous. Do not discard domain-specific knowledge just because it lacks a standard template heading.
+18. When asking for that direction, prefer a concise question that states the inferred owner and the fallback choices. Example: `I found legacy "protocol" docs that look like technical guidance. Should I 1. skip them, 2. migrate them into active guideline docs, or 3. preserve "protocol" as a project-specific doc type?`
+19. When docs are being created for the first time against an existing codebase with no prior documentation, inspect code, comments, configs, tests, and repository structure for valuable domain knowledge that goes beyond standard template headings. Surface these findings as new custom sections or new files where justified. Mark codebase-inferred facts as `Inferred from code` or `Open Question` until the user confirms them.
+
+### Review Sequence
+
+1. Read the change summary.
+2. Read the owning project docs.
+3. Read `docs/project-docs/index.md` and `docs/project-docs/technical-guidelines/index.md` when present.
+4. Read clearly named reference or archive folders such as `docs-legacy/`, `docs-old/`, `archive/`, or `reference/` when the repo is migrating from another documentation format.
+5. Decide whether any legacy material should be promoted into active optional docs such as `technical-guidelines/` or `foundation/phases/` instead of staying reference-only, using content and governed concern as the primary signal rather than legacy names.
+6. Read the relevant guideline docs when the change touches technical rules or implementation conventions.
+7. Identify impacted dependent docs.
+8. Refresh the owning docs first.
+9. Refresh summary or index docs second.
+10. Run a consistency pass.
+
+## Ownership Examples
+
+- stack or dependency changes → `foundation/architecture.md`, `technical/testing.md`
+- feature scope changes → `foundation/prd.md`, `foundation/feature-inventory.md`, `foundation/status.md`
+- detailed requirements or acceptance changes → `foundation/prd.md`, `foundation/status.md`
+- workflow or roadmap changes → `foundation/status.md`, `foundation/phases/index.md`, workflow docs if present
+- validation / CI changes → `technical/testing.md`, `getting-started.md`
+- production environment, rollout, rollback, or smoke-check changes → `operations/production-runbook.md`, `foundation/architecture.md`, `technical/testing.md`
+- API or integration changes → relevant API / integration docs plus `foundation/architecture.md`
+- optional or conditional doc inventory changes → `docs/project-docs/index.md` plus the affected optional owner docs
+- cross-cutting technical conventions or implementation rules → relevant `technical-guidelines/*.md`, `technical-guidelines/index.md`, and any summarizing core docs that reference them
+- documentation-system migration from legacy docs → active owner docs under `docs/project-docs/` first, with `docs-legacy/`, `docs-old/`, or other clearly named archive/reference folders used only as source material
+- semantic legacy-name normalization → map legacy names by content, for example `epic` or `roadmap` material to `foundation/phases/` and `protocol` or `standard` material to `technical-guidelines/` when their governed concern matches those owners
+- legacy technical-guidance promotion → `docs/project-docs/technical-guidelines/*.md`, `technical-guidelines/index.md`, and any summarizing core docs that now depend on those active guidelines
+- legacy phased-planning promotion → `docs/project-docs/foundation/phases/index.md`, the relevant phase or epic docs, `foundation/status.md`, and `docs/project-docs/index.md`
+
+## Output Contract
+
+Your result should state:
+
+1. which docs were updated
+2. why each doc was updated
+3. which docs were intentionally left unchanged
+4. any remaining consistency risks or open questions
+
+## Final Pass
+
+Before finishing, check that:
+
+1. the updated docs still match the contract in `docs/eyehateagent-contract.md`
+2. platform instruction surfaces and skills would now read the correct project-specific truth
+3. no stale summary remains in `foundation/status.md`, `docs/project-docs/index.md`, `technical-guidelines/index.md`, or other index docs
+
+## Inputs
+
+Use the change summary, affected artifacts, and current project docs provided below.

package/docs/vibes/reusable-prompts/01-sdd-execute.md

@@ -0,0 +1,34 @@
+# Spec-Driven Development (SDD) Execute
+
+## Goal
+
+Translate a newly updated project specification into tested, working code by following a strict Test-Driven Development (TDD) and Spec-Driven Development (SDD) lifecycle.
+
+## Required Behavior
+
+1. **Read the Specs:** First, read `docs/project-docs/foundation/prd.md` and `docs/project-docs/foundation/architecture.md`.
+2. **Verify Spec Completeness:** Check if the user's requested feature is documented in the specs.
+   - If the feature is NOT documented, **do not write code yet**. Instead, immediately draft the necessary additions for `foundation/prd.md` and `foundation/architecture.md` and present them to the user. Ask the user: "Should I add these specifications to the project docs and then proceed with implementation?"
+3. **Generate Tests (TDD):** If the spec is present, author the test cases that validate the acceptance criteria.
+4. **Generate Code:** Write the implementation code to pass the generated tests.
+5. **Verify Completeness:** Ensure the code passes the tests and fulfills the architectural rules defined in `foundation/architecture.md`.
+
+## Output Contract
+
+1. **Spec Mapping:** A brief list linking the code changes you are about to make to the specific lines/sections in the project docs.
+2. **Tests Authored:** The tests written to fulfill the spec.
+3. **Code Authored:** The implementation code.
+4. **Validation:** A summary of how the implementation satisfies the initial specification.
+
+## Final Pass
+
+- Does the implementation violate any constraints in `foundation/architecture.md`?
+- Are there any tests missing for the acceptance criteria listed in `foundation/prd.md`?
+- Did I write code for a feature that wasn't in the spec? (If yes, revert it).
+
+## Inputs
+
+- The user's prompt requesting the execution of a feature.
+- `docs/project-docs/foundation/prd.md`
+- `docs/project-docs/foundation/architecture.md`
+- `docs/project-docs/technical/testing.md`

package/docs/vibes/reusable-prompts/02-sdd-discuss.md

@@ -0,0 +1,27 @@
+# SDD Discuss Phase (Brainstorming)
+
+## Goal
+
+Act as a Senior Engineer / Agile Product Manager to help the user brainstorm and finalize the specifications for a new feature or architectural change *before* it gets committed to the permanent documentation or implemented in code.
+
+## Required Behavior
+
+1. **Do NOT Write Code:** This is purely a planning and discussion phase. Do not output any implementation code.
+2. **Interview the User:** Ask clarifying questions to eliminate ambiguity. Consider:
+   - Edge cases and error states.
+   - API shapes and payload structures.
+   - UI/UX constraints or responsive layouts.
+   - Data model changes (new tables, columns, relations).
+3. **Draft the Spec:** Once the user answers your questions and you reach an agreement, output a drafted, markdown-formatted snippet that is ready to be injected into the specific target documents (e.g., `foundation/prd.md`, `foundation/architecture.md`, `technical/api-contract.md`).
+4. **Final Approval:** Ask the user: "Should I execute the SDD workflow (`01-sdd-execute.md`) with these specifications?"
+
+## Output Contract
+
+1. **Your Questions:** 1-3 highly targeted technical questions about the gray areas of the feature.
+2. **The Drafted Spec:** A clear, concise markdown block representing the final agreed-upon rules.
+
+## Inputs
+
+- The user's rough feature idea or concept.
+- `docs/project-docs/foundation/prd.md` (to understand current scope)
+- `docs/project-docs/foundation/architecture.md` (to understand current stack constraints)

package/docs/vibes/skills/analysis/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: analysis
+description: "Project-aware expert-role analysis for architecture, debugging, trade-offs, risk, performance, requirements, and design questions. Reads project docs first, then applies expert structured reasoning to the current repository context."
+argument-hint: "Describe the problem, decision, artifact, or system to analyze"
+---
+
+# Analysis — Project-Aware
+
+Produces a **rigorous, expert-level analysis** of a problem, decision, artifact, or system after first reading the project documentation that defines the repository's actual context.
+
+This skill is reusable across product, backend, frontend, infrastructure, monorepo, and documentation-heavy projects. It should not assume a particular stack until the project docs confirm it.
+
+---
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+
+| `docs/project-docs/foundation/prd.md` | Clarifies goals, scope, stakeholders, and success metrics |
+| `docs/project-docs/foundation/architecture.md` | Defines stack, boundaries, integration model, constraints, and runtime assumptions |
+| `docs/project-docs/foundation/status.md` | Reveals maturity, roadmap, active workstreams, and known blockers |
+| `docs/project-docs/technical/testing.md` | Shows what validation exists and how strong the available evidence can be |
+| Relevant feature, workflow, API, or guideline docs | Supply domain-specific truth for the topic being analyzed |
+| Relevant code, logs, tests, or runtime evidence | Support findings with direct evidence rather than guesswork |
+
+If the required project docs are missing, note the gap explicitly and limit confidence accordingly.
+
+---
+
+## When To Use
+
+| Trigger | Example request |
+| --- | --- |
+| Architecture review | "Analyze this module boundary for coupling risk" |
+| Debugging | "Analyze why this workflow fails intermittently" |
+| Trade-off decision | "Analyze option A vs option B for this integration" |
+| Requirements review | "Analyze these specs for gaps and contradictions" |
+| Risk assessment | "Analyze the release risk of this change" |
+| Performance diagnosis | "Analyze where this request path will bottleneck" |
+| Product or roadmap question | "Analyze whether this feature belongs in MVP" |
+
+---
+
+## Procedure
+
+### Step 1 — Understand the question
+
+- Restate the problem in precise terms.
+- Identify the decision being made or the behavior being explained.
+- Identify what counts as success or failure.
+- Identify any missing context that materially changes the analysis.
+
+### Step 2 — Ground the analysis in project reality
+
+Read the relevant project docs first.
+
+Extract:
+
+- actual stack and runtime model
+- architecture rules and boundaries
+- scope and non-goals
+- available verification signals
+- known constraints such as team size, maturity, environment, or performance budget
+
+### Step 3 — Decompose the subject
+
+Break the problem into:
+
+- components
+- boundaries
+- dependencies
+- failure points
+- assumptions
+- decision criteria
+
+Identify the most load-bearing parts first.
+
+### Step 4 — Gather evidence
+
+Prefer direct evidence from:
+
+- code
+- tests
+- runtime logs
+- project docs
+- API or contract docs
+- existing workflows
+
+Separate:
+
+- facts
+- inferences
+- assumptions
+
+### Step 5 — Apply the right reasoning mode
+
+Use one or more of:
+
+- first-principles reasoning
+- causal reasoning
+- adversarial reasoning
+- deductive reasoning
+- inductive reasoning
+- comparative or trade-off analysis
+- probabilistic reasoning
+
+### Step 6 — Evaluate and rank
+
+When comparing options or hypotheses:
+
+- use explicit criteria
+- surface hidden costs
+- distinguish reversible vs irreversible decisions
+- distinguish local optimization vs system impact
+
+### Step 7 — Form a judgment
+
+- state the conclusion directly
+- say what is known vs inferred
+- say what could change the conclusion
+- tie the recommendation back to the project's actual constraints
+
+---
+
+## Output Contract
+
+Your output should include:
+
+1. summary
+2. analysis by area or component
+3. key findings ordered by importance
+4. recommendation or decision guidance
+5. risks and open questions
+6. confidence and evidence limitations when relevant
+
+---
+
+## Quality Checks
+
+- No claim without evidence or clearly marked assumption
+- No false precision when evidence is weak
+- No generic advice detached from project constraints
+- No vague recommendation without an actionable next step
+- No hidden stack assumptions that were not confirmed from project docs
+
+---
+
+## Anti-Patterns
+
+- Listing facts without evaluating them
+- Jumping to the first plausible conclusion
+- Treating all options as equally valid when evidence favors one
+- Recommending a rewrite when an incremental fix would solve the problem
+- Ignoring the project stage, roadmap, or non-goals in `prd.md` and `status.md`
+
+---
+
+## Natural Prompt Shapes
+
+- "Why is this failing, and what do you think is the real cause?"
+- "Analyze this decision and tell me whether it still makes sense."
+- "What are the trade-offs and risks of these two options?"
+- "Check whether these requirements or assumptions still hold up."
+
+---
+
+## Example Requests
+
+- "Analyze this module boundary for coupling risk"
+- "Analyze why this workflow fails intermittently"
+- "Analyze option A vs option B for this integration"
+- "Analyze whether this feature belongs in MVP"

package/docs/vibes/skills/api-design/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: api-design
+description: "Project-aware expert-role contract design for APIs, interfaces, repositories, services, message schemas, and module boundaries. Reads project docs first, then produces or reviews a contract consistent with the current repository."
+argument-hint: "Describe the boundary, interface, endpoint, message contract, or service behavior to design or review"
+---
+
+# Interface & API Contract Design — Project-Aware
+
+Produces a **project-aware, expert-level contract design or design review** by reading the repository's project docs first, then applying a reusable method to the current boundary type.
+
+This skill is intentionally reusable across:
+
+- HTTP APIs
+- internal service interfaces
+- repositories and adapters
+- event or message contracts
+- data-transfer schemas
+- client or SDK boundaries
+
+It should **not** assume one language, framework, transport, or architecture style until the project docs confirm them.
+
+---
+
+## Required Project Inputs
+
+| Document | Why it matters |
+| --- | --- |
+
+| `docs/project-docs/foundation/architecture.md` | Defines stack, architecture boundaries, dependency rules, and integration patterns |
+| `docs/project-docs/foundation/prd.md` | Clarifies scope, constraints, stakeholders, and non-goals |
+| `docs/project-docs/technical/testing.md` | Defines how the contract should be validated |
+| Relevant feature docs, API docs, or guidelines | Provide domain-specific rules, request/response shapes, workflows, and edge cases |
+| Existing code or contracts in the repo | Show local naming, layering, serialization, validation, and error conventions |
+
+If the repository lacks the contract-defining docs needed for the task, call that out and create or update the missing docs instead of inventing local rules in the skill.
+
+---
+
+## When To Use
+
+Use this skill when designing or reviewing one of these boundary types.
+
+| Boundary type | Typical artifacts |
+| --- | --- |
+| External HTTP / RPC API | route, handler, controller, request/response schema, auth, pagination, versioning |
+| Internal service interface | method signatures, error contract, idempotency, retries, transaction boundaries |
+| Repository or persistence boundary | interface, query contract, mapping rules, transaction semantics |
+| Adapter or integration boundary | client interface, DTOs, transport mapping, failure translation |
+| Event or message contract | payload schema, producer/consumer expectations, ordering, retry, dead-letter rules |
+| Module boundary | public interface, dependency direction, allowed imports, extension points |
+
+---
+
+## Procedure
+
+### Step 1 — Identify the contract owner
+
+Determine which layer or module owns the boundary.
+
+Questions to answer:
+
+- Is this public or internal?
+- Is it synchronous or asynchronous?
+- Is it request/response, command, query, event, or stream based?
+- Which side owns validation?
+- Which side owns retries and failure translation?
+
+Use `architecture.md` to avoid violating the project's dependency or layering rules.
+
+### Step 2 — Identify the project-specific constraints
+
+Extract from project docs:
+
+- naming conventions
+- error model
+- serialization format
+- auth and authorization expectations
+- pagination / filtering conventions
+- idempotency or transaction expectations
+- observability or auditing requirements
+- compatibility or versioning rules
+
+Do not assume REST, JSON, SQL, Clean Architecture, CQRS, or any other pattern unless the docs require it.
+
+### Step 3 — Define the contract shape
+
+Design the minimal contract that supports the required behavior.
+
+Depending on the boundary, specify:
+
+- inputs
+- outputs
+- failure modes
+- validation rules
+- side effects
+- ordering or transaction semantics
+- timeouts or retry expectations
+- invariants that must always hold
+
+Prefer explicit types or schemas over ambiguous free-form payloads.
+
+### Step 4 — Separate durable domain concepts from transport details
+
+If the project distinguishes domain models from transport or persistence models, keep them separate.
+
+Typical separations include:
+
+- domain entity vs API DTO
+- service input object vs controller request body
+- repository interface vs database table model
+- event contract vs internal aggregate or entity state
+
+Use the separation rules already defined by the project docs. Do not invent new layering rules casually.
+
+### Step 5 — Define the error contract
+
+Specify:
+
+- expected failure categories
+- how they surface to callers
+- which failures are retriable
+- which failures are validation vs business vs infrastructure errors
+- what data is safe to expose externally
+
+If the repo already defines a standard result wrapper, exception hierarchy, or error envelope, reuse it.
+
+### Step 6 — Define verification requirements
+
+Use `testing.md` to decide how the contract should be validated.
+
+Examples:
+
+- schema or serialization tests
+- handler / controller tests
+- repository or persistence tests
+- integration tests against a real dependency
+- compatibility or migration checks
+- documentation consistency review
+
+### Step 7 — Produce the design output
+
+The output should fit the repository style and include enough detail to implement safely without locking the repo into one stack-specific pattern that the docs do not support.
+
+---
+
+## Output Contract
+
+When using this skill, the output should include:
+
+1. the boundary type
+2. the project docs consulted
+3. the proposed contract shape
+4. validation and error rules
+5. ownership and dependency implications
+6. verification strategy
+7. open questions that still require product or architecture decisions
+
+---
+
+## Quality Checks
+
+Use this checklist when reviewing an existing contract:
+
+- Is the boundary owned by the correct layer or module?
+- Does the contract match project naming and error conventions?
+- Are validation rules explicit?
+- Are transport details separated from durable domain concepts where required?
+- Are failure modes documented and actionable?
+- Does the contract create hidden coupling or leak implementation details?
+- Is there a clear verification strategy in `testing.md`?
+
+---
+
+## Anti-Patterns
+
+- Embedding one stack's rules into the skill instead of reading project docs
+- Designing an interface before understanding the owning boundary
+- Mixing transport payload shape with domain concepts when the project separates them
+- Returning ambiguous success or failure semantics
+- Ignoring versioning, compatibility, or migration concerns for externally visible contracts
+- Over-designing the contract far beyond the current scope in `prd.md`
+
+---
+
+## Natural Prompt Shapes
+
+- "Design the contract for this API or service boundary."
+- "Check whether this endpoint or DTO shape is designed correctly."
+- "Define the interface, error contract, and validation rules for this boundary."
+- "Review whether this event or repository contract matches the architecture."
+
+---
+
+## Example Requests
+
+- "Design the repository contract for this feature"
+- "Review this controller and DTO boundary"
+- "Design an event payload for this workflow"
+- "Define the error contract for this external integration"