From 558f2a0ea92f26f7c0050adf24fbf52da312058c Mon Sep 17 00:00:00 2001 From: Elizabeth W Date: Mon, 25 May 2026 19:40:33 -0600 Subject: [PATCH] adding seam review skill --- .agents/skills/tdfddd-seam-review/SKILL.md | 163 +++++++++++++++++++++ docs/reference/review-checklist.md | 25 ++++ 2 files changed, 188 insertions(+) create mode 100644 .agents/skills/tdfddd-seam-review/SKILL.md diff --git a/.agents/skills/tdfddd-seam-review/SKILL.md b/.agents/skills/tdfddd-seam-review/SKILL.md new file mode 100644 index 0000000..28d1767 --- /dev/null +++ b/.agents/skills/tdfddd-seam-review/SKILL.md @@ -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 diff --git a/docs/reference/review-checklist.md b/docs/reference/review-checklist.md index 8cc8cc2..e15055a 100644 --- a/docs/reference/review-checklist.md +++ b/docs/reference/review-checklist.md @@ -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?