adding seam review skill

2026-05-25 19:40:33 -06:00
parent 5ec088c250
commit 558f2a0ea9
2 changed files with 188 additions and 0 deletions
@@ -0,0 +1,163 @@
+---
+name: tdfddd-seam-review
+description: "Evaluates how well a bounded context or seam follows TDFDDD bounded-seam review principles. Use when reviewing a bounded context, workflow seam, policy seam, or public API for intent-first naming, trust boundaries, reviewability, and seam quality."
+---
+
+# TDFDDD Seam Review
+
+## Description
+
+Evaluates whether a bounded context exposes strong bounded seams that are easy to review with high confidence.
+Use this skill to review an existing bounded context, workflow seam, policy seam, or public API and produce a report about seam quality without changing behavior.
+
+## When to Use This Skill
+
+Activate when the user:
+
+- asks to review a bounded context for clarity or seam quality
+- wants to know why a context is hard to review
+- wants an evaluation of workflow seams, policy seams, or public APIs
+- suspects naming drift, leakage, or tangled responsibilities
+- wants guidance before a bounded-seam refactor
+
+## Core Function: The Seam Review Protocol
+
+**Goal:** explain whether the code presents a reviewable bounded seam, why it is or is not working, and rank the improvements
+
+**Required input:**
+
+- target bounded context, files, or seam
+- optional concern such as naming, trust boundaries, public API sprawl, or review load
+
+If scope is unclear, infer a provisional seam under review and state it explicitly.
+
+## Review Headspace
+
+Treat names as review targets, not as automatically correct just because the initial model exists.
+A seam is strong when a reviewer can understand caller intent, authority, invariants, and outcomes without reconstructing internals.
+
+## Instructions
+
+1. Read the relevant code before making any claim.
+2. Identify the top bounded seam first.
+   - usually the context public API or the main workflow entrypoint
+   - state what command goes in and what event or failure comes out
+3. Identify the inner review seams.
+   - pure policies
+   - state transitions or model operations
+   - trust boundaries where tainted input becomes trusted
+4. Review the seam using the general bounded-seam questions:
+   - What caller intent does this seam grant?
+   - What invariant becomes true after crossing it?
+   - What tainted input becomes trusted here?
+   - What can still fail, and how is failure represented?
+   - What decisions are pure policy versus orchestration versus I/O?
+   - What internal details are leaking through the public API?
+   - If this seam were renamed by user goal instead of implementation shape, what would it be called?
+5. Apply seam-type-specific questions.
+
+### Workflow seam questions
+
+- Given command X, under what rules does this workflow emit event Y or failure Z?
+- Is the workflow mostly assembling decisions and capabilities, or is it hiding business rules inside orchestration?
+- Does the workflow expose the business outcome more clearly than the implementation steps?
+
+### Policy seam questions
+
+- What exact business or security decision is being made?
+- What inputs are sufficient for that decision?
+- Are the reasons for approval or rejection explicit enough to review?
+- Is the policy pure and deterministic?
+
+### Public API questions
+
+- Does the public surface expose one intent-first entrypoint or force the reviewer to reconstruct the context from many exports?
+- Are internals importing back through the public barrel, making the seam circular or blurry?
+- Does the API hide mechanics, or does it leak low-level helpers, transitional state names, or assembly details?
+
+## What to Look For
+
+### Strong seam signals
+
+- intent-first workflow or context entrypoint
+- explicit event and failure shapes
+- pure policy decisions with explicit reasons
+- visible trust boundaries
+- narrow public API with clear authority
+- internal modules importing direct local dependencies instead of re-entering `index.ts`
+
+### Weak seam signals
+
+- state or type names that describe pipeline progress rather than reviewer intent
+- barrels that re-export nearly everything
+- internal files importing from the public API of their own context
+- mixed concerns inside one module such as parsing, policy, model math, and artifact derivation
+- service or workflow code hiding business rules in control flow
+- reviewer needing broad context just to answer one contract question
+
+## Output Format
+
+Return a compact report with these sections:
+
+```markdown
+## Seam Under Review
+
+- Scope: ...
+- Top bounded seam: ...
+- Inner review seams: ...
+
+## What Makes This Easy or Hard to Review
+
+- Strengths: ...
+- Friction points: ...
+- Trust-boundary visibility: ...
+- Naming quality: ...
+
+## Seam Evaluation
+
+- Caller intent: ...
+- Protected invariant: ...
+- Tainted to trusted transition: ...
+- Failure contract: ...
+- Public API leakage: ...
+- Policy / workflow / IO separation: ...
+
+## Judgment
+
+- Seam quality: strong | mixed | weak
+- Main issue: ...
+- Why review load is high or low: ...
+
+## Smallest High-Value Improvements
+
+- 1. ...
+- 2. ...
+- 3. ...
+```
+
+## Naming Guidance During Review
+
+If naming is part of the problem:
+
+1. state why the current name is weak
+2. propose three alternatives when the name is important
+3. choose the option that best preserves caller intent across likely model evolution
+4. prefer intent-first names over vague ready/process labels when those better describe the protected invariant. follow the naming guidelines in "docs/explanation/naming-for-domain-modeling.md"
+
+## Constraints
+
+- Do not write implementation code unless the user explicitly asks for a refactor.
+- Do not demand extra layers if the current seam can be clarified with naming or API reduction.
+- Do not treat every state-machine name as wrong; flag it only when it increases review load or hides the actual invariant.
+- Do not weaken security or trust-boundary checks in the name of simplicity.
+
+## Success Criteria
+
+A good seam review should let a human reviewer answer:
+
+- what the main seam is
+- what it promises
+- why it is easy or hard to review
+- where trust enters and becomes trusted
+- which names or exports are increasing review load
+- what the smallest justified improvements are
@@ -46,6 +46,31 @@ Use this checklist when reviewing a design produced by a human or an LLM.
 - Can service and adapter internals be trusted mostly through seam tests and type constraints rather than line-by-line domain review?
 - Do service implementations avoid accumulating hidden business logic?

+## General bounded-seam review questions
+
+- What caller intent does this seam grant?
+- What invariant becomes true after crossing it?
+- What tainted input becomes trusted here?
+- What can still fail, and how is failure represented?
+- What decisions are pure policy versus orchestration versus I/O?
+- What internal details are leaking through the public API?
+- If this seam were renamed by user goal instead of implementation shape, what would it be called?
+
+## Applying the questions by seam type
+
+### Workflow seams
+
+- Given command X, under what rules does this workflow emit event Y or failure Z?
+- Is the workflow mostly assembling decisions and capabilities, or is it hiding business rules inside orchestration?
+- Does the workflow expose the business outcome more clearly than the implementation steps?
+
+### Policy seams
+
+- What exact business or security decision is being made?
+- What inputs are sufficient for that decision?
+- Are the reasons for approval or rejection explicit enough to review?
+- Is the policy pure and deterministic?
+
 ## Security review readiness

 - Are trust boundaries visible enough for a reviewer to identify where untrusted data enters?