@onuraslan/sdd 1.0.5

package/sdd-utility/skills/code-slop-review/references/structural-slop.md

@@ -0,0 +1,150 @@
+# Layer 1 — Structural Slop Reference
+
+AI adds code; it does not refactor. It generates the pattern it saw most often
+in training — not the pattern that fits your architecture.
+
+---
+
+## Pattern 1 — God X (Function / Class / Module / Service)
+
+Any single unit that does more than one thing at one level of abstraction —
+i.e., it has multiple responsibilities.
+
+### 1a — God Function
+
+A function with multiple responsibilities.
+
+**What to flag:**
+- Comment-separated sections inside the function
+- "and" in the function name (fetch_and_save, validate_and_send)
+- Mixed abstraction levels (DB query + string formatting in one function)
+- Deep nesting
+- Too many parameters
+
+### 1b — God Class
+
+A class with multiple unrelated responsibilities.
+
+**What to flag:**
+- Comment-separated sections
+- Multiple unrelated responsibilities (e.g., DB ops + HTTP + file I/O in one class)
+- Too many public methods
+- Too many instance variables
+- Generic responsibility names: "Manager", "Handler", "Processor", "Service"
+
+### 1c — God Module
+
+A module that exports too many unrelated things.
+
+**What to flag:**
+- Too many exports
+- Mixed concerns (e.g., date helpers + string helpers + math helpers)
+- Comment-separated sections inside the module
+- Generic file names: utils, helpers, common, shared, misc
+
+### 1d — God Service
+
+A service that handles too many business capabilities.
+
+**What to flag:**
+- Service handles many distinct business capabilities
+- Service has dependencies on many external services/repos
+- Generic service names: UserService, OrderService, PaymentService
+- Service imports from many other modules
+- Service is imported by more than half the codebase
+
+---
+
+## Pattern 2 — Semantic Duplication
+
+The same logic appearing in multiple places with different variable names or entity nouns.
+
+**What to flag:**
+- Parallel function shapes with identical structure, differing only by:
+  - Column name
+  - Role string
+  - Entity noun
+
+---
+
+## Pattern 3 — Wrong Abstraction
+
+Abstractions introduced because they exist in training data, not because the code needs them.
+
+**What to flag:**
+- Interface or base class with exactly one non-test implementor
+- Single-method wrapper class that only delegates
+- Config object used in very few places
+
+---
+
+## Pattern 4 — Scaffolding Remnants
+
+Placeholder implementations instead of real logic.
+
+**What to flag:**
+- pass statements in non-abstract functions
+- return None / return null when return type is not nullable
+- NotImplementedError / UnsupportedOperationException
+- panic("not implemented") / unimplemented!() / todo!()
+- TODO: implement / placeholder / stub comments
+
+---
+
+## Pattern 5 — Re-Inventing Existing Utilities
+
+New helper function for logic that already exists elsewhere in the codebase.
+
+**What to flag:**
+- New utility function with a near-identical counterpart already existing
+- New function with similar name/purpose to an existing utility
+
+---
+
+## Detection Checklist
+
+```
+□ Any function with multiple responsibilities?
+□ Any function with comment-separated sections?
+□ Any function with "and" in its name?
+□ Any function with deep nesting?
+□ Any class with multiple unrelated responsibilities?
+□ Any class with comment-separated sections?
+□ Any class with too many public methods or instance variables?
+□ Any class with generic responsibility name?
+□ Any module with too many exports?
+□ Any module with mixed concerns?
+□ Any module with generic name (utils/helpers/common)?
+□ Any service handling too many business capabilities?
+□ Any service with too many external dependencies?
+□ Any semantic duplication (same logic, different names)?
+□ Any interface with exactly one non-test implementor?
+□ Any single-method wrapper class?
+□ Any config object used in very few places?
+□ Any placeholder implementation (pass/null/not implemented)?
+□ Any TODO: implement / placeholder / stub comments?
+□ Any new utility that duplicates an existing one?
+```
+
+---
+
+## Severity Guide
+
+| Finding                             | Bucket       |
+|-------------------------------------|--------------|
+| Function with multiple responsibilities | 🟡 Moderate  |
+| Function that is very long          | 🟠 Important |
+| Function that is extremely long     | 🔴 Critical  |
+| Class with multiple responsibilities | 🟡 Moderate  |
+| Class that is very long             | 🟠 Important |
+| Class that is extremely long        | 🔴 Critical  |
+| Module with mixed concerns          | 🟡 Moderate  |
+| Module that is very long            | 🟠 Important |
+| Module that is extremely long       | 🔴 Critical  |
+| Service with many capabilities      | 🟠 Important |
+| Semantic duplication (per instance) | 🟠 Important |
+| Interface with single implementor   | 🟠 Important |
+| Single-method wrapper class         | 🟡 Moderate  |
+| Mixed abstraction levels in a unit  | 🟠 Important |
+| Scaffolding remnant (placeholder)   | 🔴 Critical  |
+| Re-invented existing utility        | 🟠 Important |

package/sdd-utility/skills/code-slop-review/references/test-slop.md

@@ -0,0 +1,88 @@
+# Layer 2 — Test Slop Reference
+
+AI-generated tests mirror the implementation — they pass because they were
+written alongside the code, not because they validate behavior.
+
+---
+
+## Pattern 1 — Implementation Mirror Test
+
+The test asserts internal state or intermediate values rather than observable
+behavior from the caller's perspective.
+
+**What to flag:**
+- Tests that break if you rename a private field or extract a private method
+- Tests that describe how the function does it, not what it guarantees
+
+---
+
+## Pattern 2 — Meaningless Assertions
+
+Assertions that always pass or verify nothing actionable.
+
+**What to flag:**
+- Checks for non-nullity without verifying content
+- Checks for empty/non-empty without verifying correctness
+- Type checks without behavioral assertions
+- Status code checks without payload assertions
+
+---
+
+## Pattern 3 — Happy Path Only
+
+Only the obvious success case is tested.
+
+**What to flag (missing tests for):**
+- Empty input
+- Boundary values
+- When dependencies raise exceptions
+- None / null / nil inputs
+- Duplicate values
+- Idempotency (operation called twice)
+- Negative tests (what the function guarantees it will NOT do)
+
+---
+
+## Pattern 4 — Mock Overuse
+
+Everything is mocked to make tests pass in isolation, but mocks don't represent real behavior.
+
+**What to flag:**
+- Tests that only verify a mock method was called, without checking arguments
+- Tests where mocking makes the assertion trivial
+
+---
+
+## Pattern 5 — No Test Files At All
+
+The codebase or module being reviewed has no test files whatsoever.
+
+**What to flag:**
+- No test files found in the code scope → single Critical finding
+- Do not run Patterns 1–4 if no tests exist
+
+---
+
+## Detecting Missing Tests
+
+**What to check:**
+- All public functions/methods should have corresponding tests
+
+**Do NOT flag:**
+- Private helpers
+- Constructors
+- Property getters
+- Dunder/magic methods
+
+---
+
+## Severity Guide
+
+| Finding                                      | Bucket       |
+|----------------------------------------------|--------------|
+| Implementation mirror assertion              | 🟠 Important |
+| Meaningless assertion                        | 🟡 Moderate  |
+| Happy path only (missing error cases)        | 🟠 Important |
+| Mock overuse (no meaningful assertion)       | 🟡 Moderate  |
+| No tests at all for a public function        | 🟠 Important |
+| No test files exist in the codebase/module   | 🔴 Critical  |

package/sdd-utility/skills/gap-analysis/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: gap-analysis
+description: Compare implementation results against requirements to find missing or incorrect work.
+disable-model-invocation: true
+---
+
+Ask the user for the **Requirement** (which file contains the requirements/specs). Then ask for the **Implementation** (what to analyze: git diff, specific commits, a branch, or a file/directory path). Read the requirement file to understand what should be implemented. Run the appropriate git diff command to gather the implementation changes. Analyze the diff against the requirements to identify: (1) **Missing** — required changes that weren't implemented, (2) **Extra** — unnecessary additions or changes not in the requirements, and (3) **Incorrect** — changes that don't match the requirements. Present findings to the user and ask if they want to apply fixes. If yes, fix the code and tests as needed.

package/sdd-utility/skills/glossary-builder/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: glossary-builder
+description: Build and maintain a shared project glossary for consistent terminology.
+disable-model-invocation: true
+---
+
+Auto-detect language and respond in the same language. One term at a time: ask which term, search the codebase for every plausible match, then show them as a numbered list plus an "I'll define it myself" option. If only one match exists, still confirm it rather than assuming; if zero matches exist, skip straight to the "define it myself" option. If the term already exists in the glossary, treat this as an update: re-search, show fresh candidates, replace the old entry in place — don't duplicate it. Once the user picks, save the file, ask "another term?", and repeat until done.
+
+---
+
+## Output Format
+
+Save to `docs/sdd/domain-glossary.md` in the project root. One simple sentence per term: what it means → what it maps to.
+
+```markdown
+# Domain Glossary
+_Generated: [date] | [N] terms | [N] mapped | [N] unmapped_
+
+---
+
+**Order** — A customer's request to purchase one or more products. Maps to `OrderAggregate`.
+
+**Order Status** — The current stage of an order's lifecycle (pending, paid, shipped, etc). Maps to `OrderStatus` enum.
+
+**Payment** — A transaction confirming funds received for an order. (No code match — defined by user.)
+
+---
+```

package/sdd-utility/skills/grounded-mode/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: grounded-mode
+description: Persistent grounded response mode that can be enabled or disabled by the user.
+disable-model-invocation: true
+---
+
+When enabled: state confirmed facts as facts. Clearly label any inference and briefly explain the evidence or reasoning behind it. If evidence is insufficient, say so instead of guessing. Never fabricate information or present speculation as fact. Format responses using these sections when relevant:
+
+✓ Confirmed
+→ Inference
+? Uncertain
+
+Omit any section that does not apply. Stay in this mode until explicitly disabled.

package/sdd-utility/skills/handoff/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: handoff
+description: Capture session context and decisions for another agent or follow-up session.
+disable-model-invocation: true
+---
+
+# Handoff
+
+Goal: minimize context loss after `/clear`. `/compact` summarizes context but doesn't preserve things that never made it into the repo — why a certain approach was chosen, which paths were tried and abandoned, etc. This skill writes only the information that **cannot be recovered by reading the repo** (git log, git diff, file contents) to `docs/sdd/handoff.md`.
+
+Use `handoff-resume` skill to read the handoff file in a new session.
+
+1. `mkdir -p docs/sdd` (create if missing).
+2. Review the entire session (conversation + tool calls made).
+3. Apply this filter to every candidate item:
+   - **"Could I recover this by reading `git log`, `git diff`, or the files themselves?"** → Yes → don't write it.
+   - **"Is this already documented in `CLAUDE.md` (project settings, user preferences, constraints)?"** → Yes → don't write it; those are already in the repo.
+   - No to both → write it into handoff.md.
+   - **Question asked to the user but never answered** → always include it in *Open questions*, transcribed **verbatim** (exact wording, no paraphrasing). This cannot be recovered from the repo, and the exact wording is needed so the next session can re-pose it and continue from the exact point of interruption.
+4. Generate `docs/sdd/handoff.md` **from scratch** (overwrite if exists) using the template below.
+5. Give the user a short confirmation: summarize what was written in 2-3 lines, then tell them it's safe to run `/clear`.
+
+### Template
+
+```markdown
+# Handoff — <date, e.g. 2026-07-01>
+
+## Context
+- Topic/epic being worked on: <short title>
+
+## Completed This Session
+- <bullet points, referencing the relevant commit/file, one line each>
+
+## Context Not Recoverable From the Repo
+
+### Decisions and rationale
+- <why this approach was chosen, what alternatives were considered and why they were rejected>
+
+### Tried and abandoned approaches
+- <so they aren't retried — what was tried, why it didn't work or was dropped>
+
+### User preferences / constraints
+- <preferences or constraints stated in conversation that never made it into code or comments>
+
+### Discovered gotchas / constraints
+- <environment quirks, third-party library behavior, API quirks, performance findings — anything not written into the code>
+
+### Open questions
+- <every question asked of the user in this session that still has no definitive answer — quoted verbatim, exactly as it was asked, in the order asked. Do not paraphrase or summarize. If there are none, remove this heading entirely.>
+
+## Next Steps
+1. <concrete, actionable, in order — if Open questions is non-empty, the first step must be to re-pose those questions verbatim to the user and wait for answers before starting other work>
+2. ...
+
+## Verification
+- <if applicable: how to test/reproduce — only if not already documented in the repo>
+```
+
+Don't leave empty sections in the template — if there are no abandoned approaches, remove that heading entirely rather than leaving it blank.
+
+---
+
+## Notes
+
+- This skill doesn't replace `/compact` — it's a manual "context transfer" step around `/clear`.
+- The "Context Not Recoverable From the Repo" section is the entire point of this skill — never put anything there that `git` could already surface (file listings, diff contents, commit messages).
+

package/sdd-utility/skills/handoff-resume/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: handoff-resume
+description: Resume work from a previous handoff document and recover session context.
+disable-model-invocation: true
+---
+
+# Handoff Resume
+
+Goal: quickly restore session context by reading `docs/sdd/handoff.md` at the start of a new session.
+
+1. Read `docs/sdd/handoff.md`.
+2. Absorb the content silently into context — don't dump the raw file back at the user.
+3. Give a short confirmation summary (3-5 lines): what the last state was, which decisions/constraints still apply, what the next step is.
+4. State that you're ready to continue from the first item in "Next Steps", then wait for the user's confirmation before doing anything else — never continue on your own.
+5. Delete `docs/sdd/handoff.md`.

package/sdd-utility/skills/init-feature/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: init-feature
+description: Initialize a new feature with the required structure and starting artifacts.
+disable-model-invocation: true
+---
+
+Scan the codebase to identify existing features and spawn subagents to write PRDs for each.
+
+---
+
+## Workflow
+
+### Step 1: External Interface Analysis
+
+**Announce:** "Step 1: Analyzing external interfaces..."
+
+Analyze the codebase to identify architectural layers and external interfaces. Show layers as ASCII diagram and list all bottom external interfaces.
+
+Wait for user confirmation.
+
+---
+
+### Step 2: Discover Features (Explore Agent)
+
+**Announce:** "Step 2: Discovering features..."
+
+Spawn an Explore subagent with the prompt from [references/explorer-prompt.md](references/explorer-prompt.md).
+
+Pass the layer structure and bottom external interfaces from Step 1 as input context.
+
+Wait for the Explore agent to complete.
+
+---
+
+### Step 3: Present Findings to User
+
+Show the user the list of identified features:
+
+Which features should I generate PRDs for? (e.g., "1,3,4" or "all" or "none")
+
+Wait for user to specify which features to process. Do not proceed without explicit confirmation.
+
+---
+
+### Step 4: Spawn PRD Writer Subagents
+
+**Announce:** "Step 4: Spawning PRD writer subagents..."
+
+For each confirmed feature:
+
+1. Spawn an Explore subagent with the prompt from [references/prd-writer-prompt.md](references/prd-writer-prompt.md)
+2. Replace `[feature name]`, `[feature key]`, and `[feature description]` placeholders with actual values from Step 3
+3. Run all subagents in parallel
+
+Wait for all subagents to complete.
+
+---
+
+### Step 5: Report Results
+
+**Announce:** "Step 5: PRD generation complete"
+
+Report to the user.

package/sdd-utility/skills/init-feature/references/explorer-prompt.md

@@ -0,0 +1,58 @@
+Task tool (explore):
+description: "Identify features by tracing vertical slices from top layer to bottom external interfaces"
+
+prompt:
+```
+Explore the codebase to identify features by tracing flows from top layer to bottom external interfaces.
+
+## Input Context
+
+You will be given:
+- **Layer structure:** [from External Interface Analysis]
+- **Bottom external interfaces:** [from External Interface Analysis]
+
+## CRITICAL: Exploration Discipline
+
+- **You are a photographer, not an interior designer.** Document what exists — full stop.
+- Describe **ONLY** what exists — no improvements, alternatives, or prescriptive language
+- Avoid: `should`, `could`, `would be better if`, `olmalı`, `daha iyi olur`
+
+## Trace Vertical Slices
+
+A **vertical slice** is a complete flow from one top interface (entry point) to one bottom external interface.
+
+For each vertical slice, identify:
+1. **Entry point:** Which route/page/component starts this flow?
+2. **Path:** What components/handlers/services does it traverse?
+3. **Exit point:** Which bottom external interface does it reach?
+
+## Group Vertical Slices into Features
+
+**Key Rule:** Vertical slices that share the same **user capability** or **data boundary** belong to the same feature.
+
+Group vertical slices by:
+- **User Journey:** What complete user capability does this enable?
+- **Data Boundary:** What records/entities does this operate on?
+- **Entry Point Proximity:** Where does the user interact?
+
+| ✅ Group Together | ❌ Don't Group By |
+|-------------------|-------------------|
+| "Create, view, edit, delete User" | Technical layers (UI/API/DB) |
+| "All auth-related flows" | File types |
+| Same entity/aggregate | Implementation steps |
+| | Separate CRUD operations |
+
+Assign a **feature key** to each group: lowercase, hyphen-separated (e.g., `auth`, `user-management`, `catalog`).
+
+## Report Format
+
+For each **feature** (group of vertical slices):
+
+- **Feature key:** `feature-key`
+- **Feature name:** (generic, user-capability based)
+- **Vertical slices included:** [list of top→bottom flows]
+- **Entry points:** [routes, pages, components]
+- **Bottom interfaces:** [DB tables, external APIs touched]
+- **Current behavior:** [what the feature does, no commentary]
+- **Data flow:** [how data moves through vertical slices]
+```

package/sdd-utility/skills/init-feature/references/prd-format.md

@@ -0,0 +1,122 @@
+# PRD Template
+
+Generate the following file at `docs/sdd/features/<feature-name>/prd.md`:
+
+```markdown
+# PRD: [Feature Name]
+
+| Metadata | Value |
+|----------|-------|
+| Status | Draft / In Review / Approved |
+| Version | 1.0 |
+| Created | YYYY-MM-DD |
+| Owner | [Product Owner / Team] |
+
+---
+
+## 1. Executive Summary
+
+[2-3 sentences summarizing what this feature does and why it matters. Written for executives/stakeholders who won't read the full document.]
+
+---
+
+## 2. Problem Statement
+
+[What user problem or business need does this feature address? Include current pain points and impact.]
+
+### 2.1 Current State
+[Describe the current situation without this feature]
+
+### 2.2 Desired State
+[Describe the desired situation after this feature is delivered]
+
+---
+
+## 3. Goals & Objectives
+
+### 3.1 Primary Goals
+- [Goal 1: Measurable outcome]
+- [Goal 2: Measurable outcome]
+
+### 3.2 Non-Goals
+[What this feature explicitly does NOT do - important for scope management]
+
+---
+
+## 4. Success Metrics
+
+[How will you measure if this feature is successful? Include baseline, target, and time horizon.]
+
+| Metric | Baseline | Target | Time Horizon | Measurement Method |
+|--------|----------|--------|--------------|-------------------|
+| [Metric name] | [Current value] | [Target value] | [Timeframe] | [How you'll measure] |
+
+---
+
+## 5. User Stories
+
+| ID | User Story | Acceptance Criteria | Priority |
+|----|------------|---------------------|----------|
+| US-01 | As a [user], I want to [action], so that [benefit] | - [Criterion 1]<br>- [Criterion 2] | Must have / Should have / Could have |
+| US-02 | As a [user], I want to [action], so that [benefit] | - [Criterion 1]<br>- [Criterion 2] | Must have / Should have / Could have |
+
+---
+
+## 6. Functional Requirements
+
+| ID | Requirement | Description | Priority | Dependencies |
+|----|-------------|-------------|----------|--------------|
+| FR-01 | [Title] | [What the system must do] | P0 / P1 / P2 | [Related FR IDs or external deps] |
+| FR-02 | [Title] | [What the system must do] | P0 / P1 / P2 | [Related FR IDs or external deps] |
+
+---
+
+## 7. Non-Functional Requirements
+
+### 7.1 Performance
+- [Response time, throughput, latency requirements]
+
+### 7.2 Security
+- [Authentication, authorization, data protection requirements]
+
+### 7.3 Reliability & Availability
+- [Uptime, error rate, recovery requirements]
+
+### 7.4 Scalability
+- [User load, data volume growth expectations]
+
+### 7.5 Accessibility
+- [WCAG compliance level, assistive technology support]
+
+---
+
+## 8. User Experience & Design
+
+### 8.1 Wireframes / Mockups
+[Link to or embed visual designs, or describe key UI states]
+
+### 8.2 Content & Messaging
+[Key copy, tone, localization requirements]
+
+---
+
+## 9. Technical Considerations
+
+[High-level technical approach translated from spec.md design decisions - written for technical stakeholders, not implementation detail]
+
+### 9.1 Integration Points
+[External APIs, services, or systems this feature touches]
+
+### 9.2 Technical Constraints
+[Hard constraints from the spec that affect product decisions]
+
+---
+
+## 10. Open Questions
+
+| ID | Question | Context | Decision Needed By | Owner |
+|----|----------|---------|-------------------|-------|
+| Q-01 | [Unresolved question] | [Why it matters] | [Date/milestone] | [Role] |
+```
+
+---

package/sdd-utility/skills/init-feature/references/prd-writer-prompt.md

@@ -0,0 +1,23 @@
+Task tool (general-purpose):
+description: "Writing PRD for `<feature>`..."
+
+prompt:
+```
+You are a PRD Writer. Your task is to write a Product Requirements Document (PRD) for a single feature.
+
+## Input Context
+
+You will be given:
+- **Feature Name:** [feature name from codebase scan]
+- **Feature Key:** [feature key from codebase scan]
+- **Feature Description:** [description from codebase scan - current behavior, entry point, data flow]
+- **Current Codebase State:** [explore and understand the current state]
+
+## Your Task
+
+Write a comprehensive PRD following the format at [prd-format.md](prd-format.md).
+
+## Output
+
+Write the PRD to: `docs/sdd/features/[feature-key]/prd.md`
+```

package/sdd-utility/skills/using-glossary/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: using-glossary
+description: Use the project glossary to keep terminology consistent during work.
+disable-model-invocation: true
+---
+
+If `docs/sdd/domain-glossary.md` exists in the project, read it before starting work. Keep its term-to-code mappings in mind for the rest of the task: use the same names the glossary uses, recognize a domain term when the user mentions it, and point to the matching code instead of guessing. If the file doesn't exist, proceed normally — no need to mention it unless the user brings up domain terminology.
+
+If the user describes a term in a way that conflicts with its glossary definition, flag the mismatch before proceeding — quote the glossary's definition, point out the difference, and ask which one should hold. Don't silently go with either version.
+
+If a term comes up that isn't in the glossary, just do the work — don't suggest adding it unless asked.