diff --git a/go-linter-driven-development/README.md b/go-linter-driven-development/README.md
index 7b02f3c..a8f01bf 100644
--- a/go-linter-driven-development/README.md
+++ b/go-linter-driven-development/README.md
@@ -40,11 +40,159 @@ The secret? **Intelligent combining.** When your linter says "complexity 18" and
**Five slash commands** for quick access:
-- `/go-ldd-autopilot` - Full workflow from design to commit
-- `/go-ldd-quickfix` - Quality gates loop with auto-fix
-- `/go-ldd-analyze` - Quality analysis only (read-only)
-- `/go-ldd-review` - Final verification (read-only)
-- `/go-ldd-status` - Show current progress
+| Command | Description | Duration | File Targeting |
+|---------|-------------|----------|----------------|
+| `/go-ldd-autopilot` | Full workflow from design to commit | 5-15 min | - |
+| `/go-ldd-quickfix [files]` | Quality gates loop with auto-fix | 2-5 min | β
Optional |
+| `/go-ldd-analyze [files]` | π Quality analysis only (read-only) | 1-2 min | β
Optional |
+| `/go-ldd-review [files]` | π Final verification (read-only) | 30-60 sec | β
Optional |
+| `/go-ldd-status` | Show current progress | Instant | - |
+
+## Architecture: Who Calls Who
+
+This diagram shows the complete call hierarchy of the plugin - commands, skills, and agents:
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β SLASH COMMANDS (Entry Points) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β /go-ldd-autopilot ββββββ β
+β (Full Phase 1-5) β β
+β ββββββββΆ @linter-driven-development SKILL β
+β /go-ldd-quickfix βββββββ (ORCHESTRATOR) β
+β (Phase 2-4 only) β β
+β βΌ β
+β /go-ldd-analyze βββββββββββββββΆ quality-analyzer AGENT ββββββββββββββββββ β
+β (Read-only analysis) β β
+β β β
+β /go-ldd-review ββββββββββββββββΆ [Parallel: Bash + go-code-reviewer] β β
+β (Final verification) β β
+β β β
+β /go-ldd-status ββββββββββββββββΆ [Status display - no agents] β β
+β β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββΌββββββ
+ β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββΌββββββ
+β @linter-driven-development SKILL β β
+β (Main Orchestrator) β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββΌββββββ€
+β β β
+β Phase 1: Pre-Flight ββββΆ @code-designing SKILL (design phase) β β
+β βββββΆ @testing SKILL (test-first) β β
+β β β
+β Phase 2: Analysis ββββββΆ quality-analyzer AGENT ββββββββββββββββββββββββββ β
+β (Full Mode) β β
+β β β
+β Phase 3: Fix Loop ββββββΆ quality-analyzer AGENT (Incremental Mode) β
+β βββββΆ @refactoring SKILL (apply fixes) β
+β β
+β Phase 4: Docs ββββββββββΆ @documentation SKILL β
+β β
+β Phase 5: Commit Ready ββΆ [Generate summary + options] β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β quality-analyzer AGENT β
+β (Parallel Quality Gate Orchestrator) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β Executes 3 tools IN PARALLEL (single message): β
+β β
+β ββββββββββββββββ ββββββββββββββββ βββββββββββββββββββββββββββ β
+β β Bash β β Bash β β Task β β
+β β (tests) β β (linter) β β go-code-reviewer AGENT β β
+β β β β β β β β
+β β go test ./...β β golangci-lintβ β Design debt analysis β β
+β ββββββββββββββββ ββββββββββββββββ βββββββββββββ¬ββββββββββββββ β
+β β β β β
+β ββββββββββββββββββΌβββββββββββββββββββββββββ β
+β βΌ β
+β βββββββββββββββββββββββββββ β
+β β Normalize + Combine β β
+β β Find Overlapping Issues β β
+β β Root Cause Analysis β β
+β β Prioritized Report β β
+β βββββββββββββββββββββββββββ β
+β β β
+β βΌ β
+β Returns: TOOLS_UNAVAILABLE | TEST_FAILURE | ISSUES_FOUND | CLEAN_STATE β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β go-code-reviewer AGENT β
+β (Design-Focused Code Analysis) β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
+β β
+β Tools Used: Skill Loaded: β
+β ββββββββββββ ββββββββββββ ββββββββββββββββββββββββββ β
+β β Read β β Grep β βββΆ β @pre-commit-review β β
+β β (files) β β (usage) β β SKILL (guidance) β β
+β ββββββββββββ ββββββββββββ ββββββββββββββββββββββββββ β
+β β β
+β βΌ β
+β Detects (what linters can't): β
+β π Bugs: nil deref, ignored errors, resource leaks, race conditions β
+β π΄ Design: primitive obsession, non-self-validating types, wrong architecture β
+β π‘ Readability: mixed abstraction, poor naming, comment quality β
+β π’ Polish: non-idiomatic naming, missing godoc examples β
+β β
+β Returns: Structured report with file:line, category, effort estimates β
+β β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+```
+
+### Component Summary
+
+| Component | Type | Calls | Called By |
+|-----------|------|-------|-----------|
+| `/go-ldd-autopilot` | Command | @linter-driven-development | User |
+| `/go-ldd-quickfix` | Command | @linter-driven-development (phases 2-4) | User |
+| `/go-ldd-analyze` | Command | quality-analyzer agent | User |
+| `/go-ldd-review` | Command | Bash (Γ2) + go-code-reviewer | User |
+| `/go-ldd-status` | Command | (none) | User |
+| `@linter-driven-development` | Skill | 5 skills + quality-analyzer agent | Commands |
+| `quality-analyzer` | Agent | go-code-reviewer + Bash (Γ2) | Skill, Commands |
+| `go-code-reviewer` | Agent | @pre-commit-review (guidance) | quality-analyzer |
+| `@code-designing` | Skill | - | @linter-driven-development |
+| `@testing` | Skill | - | @linter-driven-development |
+| `@refactoring` | Skill | - | @linter-driven-development |
+| `@documentation` | Skill | - | @linter-driven-development |
+| `@pre-commit-review` | Skill | - | go-code-reviewer (guidance) |
+
+## How Auto-Detection Works
+
+When you request Go code work (e.g., "implement feature X", "fix bug in handler.go"), Claude will detect that the linter-driven-development skill applies and **ask for permission**:
+
+```
+Use skill "go-linter-driven-development:linter-driven-development"?
+Claude may use instructions, code, or files from this Skill.
+
+Do you want to proceed?
+β― 1. Yes
+ 2. Yes, and don't ask again for this skill in [current-directory]
+ 3. No, and tell Claude what to do differently
+```
+
+**Recommended:** Select option 2 on first use. After that, the skill will run automatically in that directory without asking againβgiving you a seamless experience while maintaining control.
+
+**Triggers auto-detection:**
+- Action verbs: `implement`, `fix`, `build`, `add`, `refactor`, `update`, `change`, `modify`
+- Working in Go project (detects `go.mod` or `.go` files)
+
+**Example workflow:**
+```bash
+# First time in a project
+You: "implement the auth feature"
+Claude: [Asks permission]
+You: "Yes, and don't ask again" β
+
+# All subsequent times
+You: "fix bug in handler.go"
+Claude: "Using go-ldd workflow..." β Runs immediately
+```
## TL;DR - Should I Use This?
@@ -195,27 +343,40 @@ You just implement your feature. The plugin handles quality gates.
If you prefer explicit commands over automatic detection, use these:
-| Command | Perfect For | What It Does | Auto-Fix? |
-|---------|------------|--------------|-----------|
-| `/go-ldd-autopilot` | New feature from scratch | Full workflow: design β implement β fix β document β commit | β
Yes |
-| `/go-ldd-quickfix` | Existing code needs cleanup | Skips implementation, just runs quality gates and fixes | β
Yes |
-| `/go-ldd-analyze` | "What's wrong with my code?" | Analysis report only, no changes made | β No |
-| `/go-ldd-review` | Pre-commit sanity check | Quick verification: are we green? | β No |
-| `/go-ldd-status` | "Where are we?" | Shows current progress in workflow | N/A |
+| Command | Perfect For | What It Does | Auto-Fix? | Duration |
+|---------|------------|--------------|-----------|----------|
+| `/go-ldd-autopilot` | New feature from scratch | Full workflow: design β implement β fix β document β commit | β
Yes | 5-15 min |
+| `/go-ldd-quickfix [files]` | Existing code needs cleanup | Skips implementation, just runs quality gates and fixes | β
Yes | 2-5 min |
+| `/go-ldd-analyze [files]` | "What's wrong with my code?" | π Analysis report only, no changes made | β No | 1-2 min |
+| `/go-ldd-review [files]` | Pre-commit sanity check | π Quick verification: are we green? | β No | 30-60 sec |
+| `/go-ldd-status` | "Where are we?" | Shows current progress + suggests next steps | N/A | Instant |
+
+**File targeting:** Commands marked with `[files]` accept optional file patterns to analyze specific files instead of all git changes:
+
+```bash
+# Analyze specific package
+/go-ldd-analyze ./pkg/parser/
+
+# Fix issues in specific file only
+/go-ldd-quickfix ./pkg/handler.go
+
+# Review single file before commit
+/go-ldd-review ./cmd/main.go
+```
**Which one should I use?**
```bash
-# Starting fresh? Full autopilot
+# Starting fresh? Full autopilot (5-15 min)
/go-ldd-autopilot
-# Code is written, just needs to pass linter/tests?
+# Code is written, just needs to pass linter/tests? (2-5 min)
/go-ldd-quickfix
-# Want to see what's wrong before deciding whether to fix?
+# Want to see what's wrong before deciding whether to fix? (1-2 min)
/go-ldd-analyze
-# About to commit, want one final check?
+# About to commit, want one final check? (30-60 sec)
/go-ldd-review
# Lost track of where we are in a complex feature?
diff --git a/go-linter-driven-development/agents/go-code-reviewer.md b/go-linter-driven-development/agents/go-code-reviewer.md
index d0b5fe8..aa70a1c 100644
--- a/go-linter-driven-development/agents/go-code-reviewer.md
+++ b/go-linter-driven-development/agents/go-code-reviewer.md
@@ -1,12 +1,15 @@
---
name: go-code-reviewer
-description: Reviews Go code for design debt, primitive obsession, mixed abstractions, and architectural issues. Returns structured report without making changes. Used by linter-driven-development orchestrator for parallel analysis.
+description: |
+ WHEN: Invoked by quality-analyzer agent for design-focused code review.
+ Read-only analysis detecting design debt, primitive obsession, mixed abstractions, and architectural issues.
+ Returns structured report without making changes.
+tools: Read, Grep
---
You are a Go Code Design Reviewer specializing in detecting design patterns and architectural issues that linters cannot catch. You are invoked as a **read-only subagent** during the parallel analysis phase of the linter-driven development workflow.
-## Your Role
-
+
**IMPORTANT: You are READ-ONLY. Do not make changes, invoke other skills, or provide fixes. Only analyze and report findings.**
You will be provided:
@@ -15,25 +18,28 @@ You will be provided:
- **Previous findings** (optional, for incremental mode)
Your job: Analyze the code and return a **structured report** that the orchestrator can parse and combine with linter output.
+
-## Analysis Process
+
-### Step 1: Load Pre-Commit Review Skill
+
Automatically use the @pre-commit-review skill to guide your analysis. This skill contains:
- Detection checklist for 8 design issue categories
- Juiciness scoring algorithm for primitive obsession
- Examples of good vs bad patterns
- Effort estimation guidelines
+
-### Step 2: Read and Analyze Files
+
For each file in the review scope:
1. Use Read tool to examine code
2. Use Grep tool to find usage patterns across codebase
3. Apply design principles from @pre-commit-review skill
+
-### Step 3: Detect Design Issues
+
Focus on issues **linters cannot detect**:
@@ -67,14 +73,18 @@ Focus on issues **linters cannot detect**:
- Non-idiomatic naming (e.g., `SaveUser` β `Save` when receiver provides context)
- Missing godoc examples
- Minor refactoring opportunities
+
-### Step 4: Generate Structured Report
+
**CRITICAL: Output must follow exact format for orchestrator parsing.**
+
+
+
-## Output Format
+
-### For Full Review Mode
+
```
π CODE REVIEW REPORT
@@ -117,8 +127,9 @@ pkg/file.go:78 | [Issue description] | [Why it matters] | [Fix strategy] | Effor
[For each polish opportunity:]
pkg/file.go:34 | [Issue description] | [Why it matters] | [Fix strategy] | Effort: [Trivial/Moderate/Significant]
```
+
-### For Incremental Review Mode
+
```
π CODE REVIEW DELTA REPORT
@@ -150,8 +161,11 @@ pkg/file.go:78 | [Issue] | [Why still present] | [Fix strategy] | Effort: [X]
ββββββββββββββββββββββββββββββββββββββββββββββββ
pkg/file.go:123 | [New issue] | [Why it matters] | [Fix strategy] | Effort: [X]
```
+
+
+
-## Format Requirements
+
**file:line Format**: Must be exact for correlation with linter errors
- β
Correct: `pkg/parser.go:45`
@@ -168,8 +182,9 @@ pkg/file.go:123 | [New issue] | [Why it matters] | [Fix strategy] | Effort: [X]
**Fix Strategy**: Be specific and actionable
- β
Good: "Apply STORIFYING: Extract parseRawInput(), validateFields(), buildResult() functions"
- β Bad: "Refactor this function"
+
-## Incremental Mode Instructions
+
When review mode is `incremental`:
@@ -190,8 +205,9 @@ When review mode is `incremental`:
4. **Detect regressions**:
- Watch for new issues introduced by fixes
- Example: Fix complexity but introduce primitive obsession
+
-## Juiciness Scoring Algorithm
+
For primitive obsession findings, calculate juiciness score (1-10):
@@ -225,14 +241,16 @@ UserID string validation:
- Methods: NewUserID(), String(), Equals() (2 points)
= Juiciness: 8/10 β Extract UserID type
```
+
-## Performance Targets
+
- **Full review**: Complete within 30-45 seconds for typical feature (5-10 files)
- **Incremental review**: Complete within 15-20 seconds (2-3 changed files)
- **Parallel execution**: Your runtime should not block linter or tests
+
-## What You Must NOT Do
+
β **Do NOT invoke other skills** (@refactoring, @code-designing, @testing)
β **Do NOT make code changes** (you are read-only)
@@ -240,8 +258,9 @@ UserID string validation:
β **Do NOT run tests** (orchestrator handles this)
β **Do NOT make decisions for user** (just report findings)
β **Do NOT iterate** (run once and return report)
+
-## Integration with Orchestrator
+
You are invoked by the @linter-driven-development orchestrator during:
@@ -261,8 +280,9 @@ You are invoked by the @linter-driven-development orchestrator during:
- Identifies overlapping issues (same file:line)
- Generates unified fix strategies
- Prioritizes by impact and effort
+
-## Example Invocation
+
```
Review these Go files:
@@ -278,11 +298,13 @@ That's it! The agent's own instructions handle everything else:
- Detects design issues in 8 categories
- Returns structured report with effort estimates
- Operates in read-only mode
+
-## Remember
+
- You are a **reporter**, not a **fixer**
- Your output is **parsed by orchestrator**, format must be exact
- Your findings are **combined with linter errors** for smart analysis
- You enable **intelligent root cause analysis** and **unified fix strategies**
- You run **in parallel** with tests and linter for 40-50% speedup
+
diff --git a/go-linter-driven-development/agents/quality-analyzer.md b/go-linter-driven-development/agents/quality-analyzer.md
index 496c099..20ca292 100644
--- a/go-linter-driven-development/agents/quality-analyzer.md
+++ b/go-linter-driven-development/agents/quality-analyzer.md
@@ -1,12 +1,14 @@
---
name: quality-analyzer
-description: Executes parallel quality analysis (tests, linter, code review), normalizes outputs, identifies overlapping issues, and returns intelligent combined reports with root cause analysis. Supports both full and incremental modes.
+description: |
+ WHEN: Invoked by linter-driven-development in Phase 2 (full mode) and Phase 3 (incremental mode).
+ Executes parallel quality analysis (tests + linter + code review) and generates combined reports with root cause identification.
+tools: Bash, Task
---
You are a Quality Analyzer Agent that orchestrates parallel quality analysis for Go projects. You are invoked as a **read-only subagent** that runs quality gates in parallel, combines their results intelligently, and returns structured reports.
-## Your Role
-
+
**IMPORTANT: You are READ-ONLY. Do not make changes, apply fixes, or invoke refactoring skills. Only analyze and report findings.**
You will be provided:
@@ -16,8 +18,9 @@ You will be provided:
- **Previous findings** (optional, for incremental mode)
Your job: Execute parallel quality analysis and return a **structured report** with intelligent combined findings.
+
-## Core Responsibilities
+
1. **Execute parallel analysis**: Launch 3 tools simultaneously:
- Bash([PROJECT_TEST_COMMAND])
@@ -31,10 +34,11 @@ Your job: Execute parallel quality analysis and return a **structured report** w
4. **Root cause analysis**: Use LLM reasoning to understand underlying problems
5. **Generate reports**: Output full analysis or delta report based on mode
+
-## Workflow
+
-### Phase A: Pre-Flight Check (Command Discovery)
+
**If `project_commands` parameter is provided:**
- β
Use them directly (fast path - orchestrator already discovered)
@@ -53,8 +57,9 @@ Your job: Execute parallel quality analysis and return a **structured report** w
- Check: `which golangci-lint`
6. If fallbacks fail:
- Return **TOOLS_UNAVAILABLE** status with details
+
-### Phase B: Parallel Execution
+
**Step 1: Launch all quality gates simultaneously**
@@ -82,8 +87,9 @@ Tool Call 3: Task
**Step 3: Check test results FIRST**
- If tests failed β Return **TEST_FAILURE** immediately (skip Phases C-E)
- If tests passed β Continue to Phase C
+
-### Phase C: Normalize Results
+
**Note:** Only execute when tests PASS. Tests are binary (pass/fail) and not normalized as "issues".
@@ -99,8 +105,9 @@ normalized_issue:
message: "Cognitive complexity 18 (>15)"
raw_output: "..."
```
+
-### Phase D: Find Overlapping Issues
+
Group issues by location (file:line):
@@ -113,8 +120,9 @@ overlapping_group:
- source: review, category: design, message: "Mixed abstraction levels"
- source: review, category: design, message: "Defensive null checking"
```
+
-### Phase E: Root Cause Analysis (LLM Reasoning)
+
For each overlapping group:
1. List all issues at this location
@@ -142,10 +150,13 @@ Root Cause Analysis:
```
**Important:** No fix suggestions - just the analysis. The orchestrator passes this to @refactoring skill.
+
+
+
-## Output Format
+
-### Status Types
+
Return one of four status types:
@@ -153,8 +164,9 @@ Return one of four status types:
**TEST_FAILURE**: Tests ran but failed (test cases failed)
**ISSUES_FOUND**: Tests passed, tools ran, but linter/reviewer found quality issues
**CLEAN_STATE**: Tests passed, linter clean, reviewer clean - all quality gates green
+
-### Full Mode Output (Initial Analysis)
+
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
@@ -217,8 +229,9 @@ Total fix targets: [N] overlapping groups + [N] isolated = [N] fixes
STATUS: [TOOLS_UNAVAILABLE | TEST_FAILURE | ISSUES_FOUND | CLEAN_STATE]
```
+
-### Incremental Mode Output (After Fixes)
+
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
@@ -256,8 +269,9 @@ RESOLUTION DETAILS
STATUS: [TEST_FAILURE | ISSUES_FOUND | CLEAN_STATE]
```
+
-### TOOLS_UNAVAILABLE Report
+
```yaml
status: TOOLS_UNAVAILABLE
@@ -274,8 +288,9 @@ unavailable_tools:
message: "Cannot proceed: 2 tools unavailable. Fix tool issues and re-run."
```
+
-### TEST_FAILURE Report
+
```yaml
status: TEST_FAILURE
@@ -296,10 +311,11 @@ tests:
message: "Tests failed. Fix failing tests before proceeding to quality analysis."
```
+
-## Error Handling
+
-### Partial Failure Handling
+
When tools execute but fail mid-execution, continue with available data:
@@ -331,8 +347,9 @@ message: "Tests passed. Code review failed (timeout). Showing linter findings on
```
**Key Principle:** As long as tests pass, return ISSUES_FOUND/CLEAN_STATE and provide whatever quality data is available.
+
-## File Parameter Usage
+
The `files` parameter is interpreted differently by each tool:
@@ -350,14 +367,16 @@ The `files` parameter is interpreted differently by each tool:
- **Reviewer**: USES `files` parameter - reviews specific files only
- Reason: Focused review on new/changed code
- Passes file list to go-code-reviewer agent
+
-## Performance Targets
+
- **Full analysis**: Complete within 60-90 seconds for typical feature (5-10 files)
- **Incremental analysis**: Complete within 30-45 seconds (2-3 changed files)
- **Parallel execution**: All 3 tools run simultaneously for maximum efficiency
+
-## What You Must NOT Do
+
β **Do NOT apply fixes** (that's @refactoring skill's job)
β **Do NOT make decisions for user** (just report findings)
@@ -365,8 +384,9 @@ The `files` parameter is interpreted differently by each tool:
β **Do NOT run iterative loops** (orchestrator handles that)
β **Do NOT invoke other skills** beyond go-code-reviewer agent
β **Do NOT make code changes** (you are read-only)
+
-## Integration with Orchestrator
+
You are invoked by the @linter-driven-development orchestrator during:
@@ -385,10 +405,11 @@ You are invoked by the @linter-driven-development orchestrator during:
- Continue to next fix (if progress made)
- Enter Test Focus Mode (if tests failed)
- Complete loop (if clean state achieved)
+
-## Example Invocation
+
-### Full Mode (Initial Analysis)
+
```
Analyze code quality for this Go project.
@@ -407,8 +428,9 @@ Files to analyze:
Run all quality gates in parallel and return combined analysis.
```
+
-### Incremental Mode (After Fix Applied)
+
```
Re-analyze code quality after refactoring.
@@ -440,8 +462,11 @@ Previous findings:
Run quality gates and return delta report (what changed).
```
+
+
+
-## Remember
+
- You are a **quality gate orchestrator**, not a **fixer**
- Your output is **parsed by orchestrator**, format must be exact
@@ -449,3 +474,4 @@ Run quality gates and return delta report (what changed).
- You run all tools **in parallel** for maximum efficiency
- You return one of 4 statuses: **TOOLS_UNAVAILABLE** | **TEST_FAILURE** | **ISSUES_FOUND** | **CLEAN_STATE**
- Tests always take priority - return **TEST_FAILURE** immediately if tests fail
+
diff --git a/go-linter-driven-development/commands/go-ldd-analyze.md b/go-linter-driven-development/commands/go-ldd-analyze.md
index b6fabc3..f3c948b 100644
--- a/go-linter-driven-development/commands/go-ldd-analyze.md
+++ b/go-linter-driven-development/commands/go-ldd-analyze.md
@@ -1,11 +1,19 @@
---
name: go-ldd-analyze
description: Run quality analysis only - invoke quality-analyzer agent and display combined report without auto-fixing
+argument-hint: "[file_pattern]"
+allowed-tools:
+ - Read
+ - Grep
+ - Bash
+ - Task
---
Run comprehensive quality analysis with intelligent combining of test results, linter findings, and code review feedback.
-**This command does NOT auto-fix anything** - it provides read-only analysis with overlapping issue detection and root cause analysis.
+> **π READ-ONLY COMMAND**
+> This command performs analysis only and makes NO changes to your code.
+> For auto-fix capability, use `/go-ldd-quickfix` instead.
Execute these steps:
@@ -35,15 +43,21 @@ Search project documentation to find test and lint commands:
- Test: `go test ./...`
- Lint: `golangci-lint run --fix`
-## Step 2: Identify Changed Files
+## Step 2: Identify Files to Analyze
-Use git to find files that have changed:
+!`git status --porcelain`
+!`git diff --name-only --diff-filter=ACMR HEAD`
-```bash
-git diff --name-only --diff-filter=ACMR HEAD | grep '\.go$'
-```
+**If arguments provided** (`$ARGUMENTS`):
+- Use as file pattern (e.g., `./pkg/parser/*.go`, `./pkg/parser/`)
+- Validate files exist with glob/ls
-If no git repository or no changes, analyze all `.go` files in the project (excluding vendor/, testdata/).
+**Otherwise** (default behavior):
+- Use git to find changed files:
+ ```bash
+ git diff --name-only --diff-filter=ACMR HEAD | grep '\.go$'
+ ```
+- If no git repository or no changes, analyze all `.go` files in the project (excluding vendor/, testdata/)
## Step 3: Invoke Quality Analyzer Agent
@@ -89,7 +103,14 @@ The agent returns:
## Example Usage
```bash
+# Analyze all changed files (default)
/go-ldd-analyze
+
+# Analyze specific package
+/go-ldd-analyze ./pkg/parser/
+
+# Analyze specific file
+/go-ldd-analyze ./pkg/parser/parser.go
```
This will:
diff --git a/go-linter-driven-development/commands/go-ldd-autopilot.md b/go-linter-driven-development/commands/go-ldd-autopilot.md
index 8b50bfa..ddee39b 100644
--- a/go-linter-driven-development/commands/go-ldd-autopilot.md
+++ b/go-linter-driven-development/commands/go-ldd-autopilot.md
@@ -1,13 +1,16 @@
---
name: go-ldd-autopilot
-description: Start complete linter-driven autopilot workflow (Phase 1-6)
+description: Start complete linter-driven autopilot workflow (Phase 1-5)
+allowed-tools: [] # Delegates everything to @linter-driven-development skill
---
Invoke the @linter-driven-development skill to run the complete autopilot workflow from design through commit-ready.
+β±οΈ **Estimated Duration**: 5-15 minutes (depends on feature complexity and issues found)
+
The skill will automatically:
1. Run Pre-Flight Check (detect intent, find commands, verify Go project)
-2. Execute all 6 phases with 2 quality gates
+2. Execute all 5 phases with 2 quality gates
3. Use parallel analysis (tests + linter + go-code-reviewer agent)
4. Generate intelligent combined reports
5. Auto-fix all issues iteratively
diff --git a/go-linter-driven-development/commands/go-ldd-quickfix.md b/go-linter-driven-development/commands/go-ldd-quickfix.md
index 4e9e82f..59f86a0 100644
--- a/go-linter-driven-development/commands/go-ldd-quickfix.md
+++ b/go-linter-driven-development/commands/go-ldd-quickfix.md
@@ -1,10 +1,14 @@
---
name: go-ldd-quickfix
description: Run quality gates loop until all green (tests+linter+review β fix β repeat)
+argument-hint: "[file_pattern]"
+allowed-tools: [] # Delegates to @linter-driven-development skill
---
Execute the quality gates loop for already-implemented code that needs cleanup.
+β±οΈ **Estimated Duration**: 2-5 minutes (depends on number of issues found)
+
Run these phases from @linter-driven-development skill:
**Phase 2**: Parallel Analysis
diff --git a/go-linter-driven-development/commands/go-ldd-review.md b/go-linter-driven-development/commands/go-ldd-review.md
index 4f040fa..9b1dea5 100644
--- a/go-linter-driven-development/commands/go-ldd-review.md
+++ b/go-linter-driven-development/commands/go-ldd-review.md
@@ -1,10 +1,23 @@
---
name: go-ldd-review
description: Check if code is commit-ready (final verification, no auto-fix)
+argument-hint: "[file_pattern]"
+allowed-tools:
+ - Read
+ - Grep
+ - Bash
+ - Task
---
Run final verification checks **without** the auto-fix loop.
+> **π READ-ONLY COMMAND**
+> This command performs verification only and makes NO changes to your code.
+> For auto-fix capability, use `/go-ldd-quickfix` instead.
+
+!`git status --porcelain`
+!`git diff --stat`
+
Execute these steps:
1. **Discover commands** from project docs (README, CLAUDE.md, Makefile, etc.)
diff --git a/go-linter-driven-development/commands/go-ldd-status.md b/go-linter-driven-development/commands/go-ldd-status.md
index 43df563..4adf84a 100644
--- a/go-linter-driven-development/commands/go-ldd-status.md
+++ b/go-linter-driven-development/commands/go-ldd-status.md
@@ -1,8 +1,14 @@
---
name: go-ldd-status
description: Show current workflow status and progress
+allowed-tools:
+ - Read
+ - Bash(git *)
---
+!`git status --porcelain`
+!`git diff --stat`
+
Display current implementation status:
π Current Context:
@@ -21,4 +27,12 @@ Display current implementation status:
π― Next Action:
[What happens next in the workflow]
+## Suggested Next Steps
+
+Based on current status:
+- **Tests failing?** β Fix tests, then run `/go-ldd-analyze`
+- **Linter errors?** β Run `/go-ldd-quickfix` for auto-fix loop
+- **Code complete?** β Run `/go-ldd-review` for commit readiness check
+- **Starting new work?** β Run `/go-ldd-autopilot` for full workflow
+
Perfect for: "where are we?", "what's the status?", "what's next?"
diff --git a/go-linter-driven-development/skills/code-designing/SKILL.md b/go-linter-driven-development/skills/code-designing/SKILL.md
index e935476..a4ca266 100644
--- a/go-linter-driven-development/skills/code-designing/SKILL.md
+++ b/go-linter-driven-development/skills/code-designing/SKILL.md
@@ -1,40 +1,58 @@
---
name: code-designing
-description: Domain type design and architectural planning for Go code. Use when planning new features, designing self-validating types, preventing primitive obsession, or when refactoring reveals need for new types. Focuses on vertical slice architecture and type safety.
+description: |
+ Domain type design and architectural planning for Go code.
+ Use when planning new features, designing self-validating types, preventing primitive obsession, or when refactoring reveals need for new types.
+ Focuses on vertical slice architecture and type safety.
---
-# Code Designing
-
+
Domain type design and architectural planning for Go code.
Use when planning new features or identifying need for new types during refactoring.
-## When to Use
+**Reference**: See `reference.md` for complete design principles and examples.
+
+
+
+1. **Analyze Architecture**: Check for vertical vs horizontal slicing
+2. **Understand Domain**: Identify problem domain, concepts, invariants
+3. **Identify Core Types**: Find primitives that need type wrappers
+4. **Design Self-Validating Types**: Create types with validating constructors
+5. **Plan Package Structure**: Vertical slices by feature
+6. **Output Design Plan**: Present structured plan before implementation
+
+Ready to implement? Use @testing skill for test structure.
+
+
+
- Planning a new feature (before writing code)
- Refactoring reveals need for new types (complexity extraction)
- Linter failures suggest types should be introduced
- When you need to think through domain modeling
+
-## Purpose
+
Design clean, self-validating types that:
- Prevent primitive obsession
- Ensure type safety
- Make validation explicit
- Follow vertical slice architecture
+
-## Workflow
-
-### 0. Architecture Pattern Analysis (FIRST STEP)
+
+
**Default: Always use vertical slice architecture** (feature-first, not layer-first).
Scan codebase structure:
-- **Vertical slicing**: `internal/feature/{handler,service,repository,models}.go` β
-- **Horizontal layering**: `internal/{handlers,services,domain}/feature.go` β οΈ
+- **Vertical slicing**: `internal/feature/{handler,service,repository,models}.go`
+- **Horizontal layering**: `internal/{handlers,services,domain}/feature.go`
-**Decision Flow**:
+
1. **Pure vertical** β Continue pattern, implement as `internal/[new-feature]/`
2. **Pure horizontal** β Propose: Start migration with `docs/architecture/vertical-slice-migration.md`, implement new feature as first vertical slice
3. **Mixed (migrating)** β Check for migration docs, continue pattern as vertical slice
+
**Always ask user approval with options:**
- Option A: Vertical slice (recommended for cohesion/maintainability)
@@ -51,16 +69,16 @@ Scan codebase structure:
```
See reference.md section #3 for detailed patterns.
+
----
-
-### 1. Understand Domain
+
- What is the problem domain?
- What are the main concepts/entities?
- What are the invariants and rules?
- How does this fit into existing architecture?
+
-### 2. Identify Core Types
+
Ask for each concept:
- Is this currently a primitive (string, int, float)?
- Does it have validation rules?
@@ -68,8 +86,9 @@ Ask for each concept:
- Is it used across multiple places?
If yes to any β Consider creating a type
+
-### 3. Design Self-Validating Types
+
For each type:
```go
// Type definition
@@ -89,8 +108,9 @@ func (t TypeName) SomeMethod() result {
// Type-specific logic
}
```
+
-### 4. Plan Package Structure
+
- **Vertical slices**: Group by feature, not layer
- Each feature gets its own package
- Within package: separate by role (service, repository, handler)
@@ -110,8 +130,9 @@ domain/user.go
services/user_service.go
repository/user_repository.go
```
+
-### 5. Design Orchestrating Types
+
For types that coordinate others:
- Make fields private
- Validate dependencies in constructor
@@ -142,36 +163,39 @@ func (s *Service) DoSomething() error {
return s.repo.Save(...)
}
```
+
-### 6. Review Against Principles
+
Check design against (see reference.md):
- [ ] No primitive obsession
- [ ] Types are self-validating
- [ ] Vertical slice architecture
- [ ] Types designed around intent, not just shape
- [ ] Clear separation of concerns
+
-## Output Format
+
+
After design phase:
```
-π¨ DESIGN PLAN
+DESIGN PLAN
Feature: [Feature Name]
Core Domain Types:
-β
UserID (string) - Self-validating, prevents empty IDs
-β
Email (string) - Self-validating, RFC 5322 validation
-β
Age (int) - Self-validating, range 0-150
+- UserID (string) - Self-validating, prevents empty IDs
+- Email (string) - Self-validating, RFC 5322 validation
+- Age (int) - Self-validating, range 0-150
Orchestrating Types:
-β
UserService - Coordinates user operations
+- UserService - Coordinates user operations
Dependencies: Repository, Notifier
Methods: CreateUser, GetUser, UpdateUser
Package Structure:
-π user/
+user/
βββ user.go # UserID, Email, Age, User
βββ service.go # UserService
βββ repository.go # Repository interface + implementations
@@ -197,18 +221,18 @@ Next Steps:
Ready to implement? Use @testing skill for test structure.
```
+
-## Key Principles
-
+
See reference.md for detailed principles:
- Primitive obsession prevention (Yoke design strategy)
- Self-validating types
- Vertical slice architecture
- Types around intent and behavior, not just shape
- Single responsibility per type
+
-## Pre-Code Review Questions
-
+
Before writing code, ask:
- Can logic be moved into smaller custom types?
- Is this type designed around intent and behavior?
@@ -219,3 +243,16 @@ Before writing code, ask:
Only after satisfactory answers, proceed to implementation.
See reference.md for complete design principles and examples.
+
+
+
+Design phase is complete when ALL of the following are true:
+
+- [ ] Architecture pattern analyzed (vertical/horizontal/mixed)
+- [ ] Core domain types identified with validation rules
+- [ ] Self-validating type design documented
+- [ ] Package structure follows vertical slice pattern
+- [ ] Design decisions documented with rationale
+- [ ] Pre-code review questions answered satisfactorily
+- [ ] Design plan output presented to user
+
diff --git a/go-linter-driven-development/skills/documentation/SKILL.md b/go-linter-driven-development/skills/documentation/SKILL.md
index ba6659c..2c01a49 100644
--- a/go-linter-driven-development/skills/documentation/SKILL.md
+++ b/go-linter-driven-development/skills/documentation/SKILL.md
@@ -1,42 +1,60 @@
---
name: documentation
-description: Creates comprehensive feature documentation for humans and AI to understand features, resolve bugs, and extend functionality. Use after complete feature implementation (may span multiple commits). Generates feature docs, updates godoc, and creates testable examples.
+description: |
+ Creates comprehensive feature documentation for humans and AI to understand features, resolve bugs, and extend functionality.
+ Use after complete feature implementation (may span multiple commits).
+ Generates feature docs, updates godoc, and creates testable examples.
---
-# Feature Documentation
-
+
Creates comprehensive feature documentation for humans and AI to use for
future bug resolution, feature extensions, and codebase understanding.
-## When to Use
+This is NOT a changelog - it's an introduction to the feature.
+
+**Reference**: See `reference.md` for complete documentation checklist and examples.
+
+
+
+1. **Understand feature scope** - Review all commits related to the feature
+2. **Analyze architecture** - Identify core types, data flow, design decisions
+3. **Generate docs/[feature-name].md** - Problem/solution, architecture, usage
+4. **Update package godoc** - Reflect feature's role
+5. **Add type documentation** - Explain purpose and design decisions
+6. **Create testable examples** - Example_* functions for complex types
+7. **Validate** - Can future you/AI understand the feature without reading all code?
+
+
+
- After a complete feature is implemented (may span multiple commits)
- When adding significant new functionality to the codebase
- NOT for: individual commits, bug fixes, minor refactors
+
-## Purpose
+
Generate documentation that helps:
- **Humans**: Understand what the feature does and how to use it
- **AI**: Context for future bug fixes and feature extensions
- **Team**: Onboarding and knowledge sharing
+
-This is NOT a changelog - it's an introduction to the feature.
-
-## Workflow
+
-### 1. Understand Feature Scope
+
- Review all commits related to the feature
- Identify all modified/new files
- Understand the problem being solved
- Map out integration points with existing system
+
-### 2. Analyze Architecture
+
- Identify core domain types
- Map data/control flow
- Document design decisions (WHY choices were made)
- Note patterns used (vertical slice, self-validating types, etc.)
+
-### 3. Generate Documentation Artifacts
-
+
**Primary: Feature Documentation** (`docs/[feature-name].md`)
- Problem & solution: What problem does this solve?
- Architecture: How does it work?
@@ -47,15 +65,18 @@ This is NOT a changelog - it's an introduction to the feature.
- Update package godoc to reflect feature's role
- Add godoc to key types explaining their purpose
- Create testable examples (Example_* functions) when helpful
+
-### 4. Validate Documentation
+
- Can someone unfamiliar understand the feature?
- Can AI use this for bug fixes without reading all code?
- Are design decisions clearly explained?
- Are integration points documented?
+
-## Documentation Template
+
+
```markdown
# [Feature Name]
@@ -77,10 +98,8 @@ This is NOT a changelog - it's an introduction to the feature.
- Example: "Vertical slice structure groups all user logic together for easier maintenance"
### Data Flow
-```
[Step-by-step flow diagram or description]
Input β Validation β Processing β Storage β Output
-```
### Integration Points
- **Consumed by**: [What uses this feature]
@@ -90,24 +109,10 @@ Input β Validation β Processing β Storage β Output
## Usage
### Basic Usage
-```go
-// Common case example
-package main
-
-func example() {
- // Real, runnable code
-}
-```
+[Common case example with real, runnable code]
### Advanced Scenarios
-```go
-// Complex case example
-package main
-
-func advancedExample() {
- // Real, runnable code showing edge cases
-}
-```
+[Complex case example showing edge cases]
## Testing Strategy
- **Unit Tests**: [What's covered, approach]
@@ -124,10 +129,11 @@ func advancedExample() {
- [External documentation]
- [Design patterns used]
```
+
-## Code Comment Guidelines
+
-**Package-Level Documentation:**
+
```go
// Package [name] provides [high-level purpose].
//
@@ -145,8 +151,9 @@ func advancedExample() {
// - [Why certain patterns were used]
package name
```
+
-**Type-Level Documentation:**
+
```go
// TypeName represents [domain concept].
//
@@ -163,8 +170,9 @@ type TypeName struct {
// ...
}
```
+
-**Testable Examples:**
+
```go
// Example_TypeName_Usage demonstrates typical usage of TypeName.
func Example_TypeName_Usage() {
@@ -180,23 +188,25 @@ func Example_TypeName_Validation() {
// Output: true
}
```
+
-## Output Format
+
+
After generating documentation:
```
-π FEATURE DOCUMENTATION COMPLETE
+FEATURE DOCUMENTATION COMPLETE
Feature: [Feature Name]
Generated Artifacts:
-β
docs/[feature-name].md (created)
-β
Package godoc updated in [package]/[file].go
-β
Type documentation for:
+- docs/[feature-name].md (created)
+- Package godoc updated in [package]/[file].go
+- Type documentation for:
- TypeName1 ([file]:line)
- TypeName2 ([file]:line)
-β
Testable examples:
+- Testable examples:
- Example_TypeName1_Usage
- Example_TypeName2_Validation
@@ -210,7 +220,7 @@ Documentation covers:
- Testing strategy
- Future considerations
-π Next Steps:
+Next Steps:
1. Review docs/[feature-name].md for accuracy
2. Run `go test` to verify testable examples execute correctly
3. Consider: Does this help future you/AI understand the feature?
@@ -221,9 +231,9 @@ Would you like to:
3. Add more examples
4. Add testable examples to code
```
+
-## Key Principles
-
+
**Documentation is NOT:**
- A changelog of commits
- Implementation details without context
@@ -244,3 +254,16 @@ When AI tools read this documentation for bug fixes or extensions:
- They should see how it integrates with the system
See reference.md for complete documentation checklist and examples.
+
+
+
+Documentation is complete when ALL of the following are true:
+
+- [ ] Feature doc created at docs/[feature-name].md with all sections
+- [ ] Package godoc updated to reflect feature's role
+- [ ] Key types have godoc explaining purpose and design decisions
+- [ ] Testable examples created for complex/core types
+- [ ] Someone unfamiliar can understand the feature
+- [ ] AI can use this for bug fixes without reading all code
+- [ ] Design decisions are clearly explained with rationale
+
diff --git a/go-linter-driven-development/skills/linter-driven-development/SKILL.md b/go-linter-driven-development/skills/linter-driven-development/SKILL.md
index f214dd5..542c0ad 100644
--- a/go-linter-driven-development/skills/linter-driven-development/SKILL.md
+++ b/go-linter-driven-development/skills/linter-driven-development/SKILL.md
@@ -1,90 +1,79 @@
---
name: linter-driven-development
description: |
- Orchestrates complete autopilot workflow: design β test β lint β refactor β review β commit.
- AUTO-INVOKES when user wants to implement code: "implement", "ready", "execute", "continue",
- "do step X", "next task", "let's go", "start coding". Runs automatically through all phases
- until commit-ready. Uses parallel linter+review analysis and intelligent combined reports.
- For: features, bug fixes, refactors. Requires: Go project (go.mod).
+ WHEN: User requests Go code work (implement, fix, add, refactor) or mentions @ldd in a Go project.
+ Orchestrates complete workflow (Phases 1-5): design β test β implement β lint β fix β documentation.
+ Auto-triggers parallel quality analysis and iterative fix loop until code is commit-ready.
---
-# Linter-Driven Development Workflow
-
-META ORCHESTRATOR for implementation workflow: design β test β lint β refactor β review β commit.
+
+Meta orchestrator for Go implementation workflow: design β test β lint β refactor β review β commit.
Use for any commit: features, bug fixes, refactors.
-## When to Use
-- Implementing any code change that should result in a commit
-- Need automatic workflow management with quality gates
-- Want to ensure: clean code + tests + linting + design validation
+**Reference**: See `reference.md` for agent prompt templates, example reports, and output formats.
+
-## Pre-Flight Check (ALWAYS RUN FIRST)
+
+**Auto-Pilot Behavior**: This skill triggers automatically when Go code work is detected. After permission is granted, announce: **"Using go-ldd workflow for this Go code work"** and proceed to pre-flight check.
-Before starting the autopilot workflow, verify all conditions are met:
+**Trigger Conditions**:
+- User requests Go code work (implement, fix, add, refactor, update, change, modify, etc.)
+- User mentions "ldd" or "@ldd" (shorthand for linter-driven-development)
+- Working directory contains Go project (go.mod or .go files)
+
-### 1. Confirm Implementation Intent
-Look for keywords indicating the user wants to implement code:
-- **Direct keywords**: "implement", "ready", "execute", "do", "start", "continue", "next", "build", "create"
-- **Step references**: "step 1", "task 2", "next task", "do step X"
-- **Explicit invocation**: "@linter-driven-development"
+
+**Immediate Action**: Run Pre-Flight Check, then execute phases sequentially until commit-ready.
-### 2. Verify Go Project
-Check that `go.mod` exists in the project root or parent directories.
+1. **Pre-Flight**: Verify Go project, find test/lint commands, identify plan context
+2. **Phase 1**: Design types (if needed) β Write tests β Implement code
+3. **Phase 2**: Run quality-analyzer agent β Route based on status
+4. **Phase 3**: Fix loop until CLEAN_STATE
+5. **Phase 4**: Documentation
+6. **Phase 5**: Present commit summary with options
+
+
+
+
+
+**ALWAYS RUN FIRST**
+
+
+Look for keywords: "implement", "ready", "execute", "do", "start", "continue", "next", "build", "create", "step 1", "task 2", or explicit "@linter-driven-development", "@ldd", "ldd"
+
-### 3. Find Project Commands
-Discover test and lint commands by reading project documentation:
+
+Check that `go.mod` exists in the project root or parent directories.
+
+
**Search locations** (in order):
1. Project docs: `README.md`, `CLAUDE.md`, `agents.md`
2. Build configs: `Makefile`, `Taskfile.yaml`, `.golangci.yaml`
3. Git repository root for workspace-level commands
**Extract commands**:
-- **Test command**: Look for `go test`, `make test`, `task test`, or similar
-- **Lint command**: Look for `golangci-lint run --fix`, `make lint`, `task lintwithfix`, or similar
-- **Prefer**: Commands with autofix capability (e.g., `--fix` flag)
-
-**Fallback defaults** (if not found in docs):
-- Tests: `go test ./...`
-- Linter: `golangci-lint run --fix`
-
-**If fallbacks don't work**:
-- Ask user: "What commands should I use for testing and linting?"
-- Document discovered commands in project docs for future runs
-
-**Store discovered commands** for use throughout the workflow.
-
-### 4. Identify Plan Context
-Scan conversation history (last 50 messages) for:
-- Step-by-step implementation plan
-- Which step the user wants to implement
-- Any design decisions or architectural context
-
-### 5. Decision Tree
-
-β
**All conditions met β AUTOPILOT ENGAGED**
-- Announce: "Engaging autopilot mode for [feature/step description]"
-- Proceed directly to Phase 1
-
-β **Unclear intent or missing context β ASK FOR CONFIRMATION**
-- "I detected you want to implement something. Should I start the autopilot workflow?"
-- Clarify which step to implement if multiple options exist
-
-β **No plan found β SUGGEST CREATING PLAN FIRST**
-- "I don't see an implementation plan. Would you like me to help create one first?"
-- Offer to use @code-designing skill for design planning
-
-β **Not a Go project β EXPLAIN LIMITATION**
-- "This skill requires a Go project with go.mod. Current project doesn't appear to be Go."
-
-## Workflow Phases
-
-### Phase 1: Implementation Foundation
-
+- **Test command**: `go test`, `make test`, `task test`
+- **Lint command**: `golangci-lint run --fix`, `make lint`, `task lintwithfix`
+- **Fallbacks**: `go test ./...` and `golangci-lint run --fix`
+
+
+
+Scan conversation history (last 50 messages) for step-by-step plan and which step to implement.
+
+
+
+
+
+
+
+
+
+
+
**Design Architecture** (if new types/functions needed):
- Invoke @code-designing skill
- Output: Type design plan with self-validating domain types
-- When in plan mode, invoke with plan mode flag
**Write Tests First**:
- Invoke @testing skill for guidance
@@ -95,387 +84,115 @@ Scan conversation history (last 50 messages) for:
- Follow coding principles from coding_rules.md
- Keep functions <50 LOC, max 2 nesting levels
- Use self-validating types, prevent primitive obsession
-- Apply storifying pattern for readable top-level functions
-
-### Phase 2: Quality Analysis (Agent is the Gate)
+
-**Invoke quality-analyzer agent** for parallel quality analysis:
+
+**Invoke quality-analyzer agent** for parallel quality analysis.
+See `reference.md` β "Agent Prompt Templates" for full prompt.
-```
-Task(subagent_type: "quality-analyzer")
-
-Prompt:
-"Analyze code quality for this Go project.
-
-Mode: full
-
-Project commands:
-- Test: [PROJECT_TEST_COMMAND from Pre-Flight Check]
-- Lint: [PROJECT_LINT_COMMAND from Pre-Flight Check]
-
-Files to analyze:
-[list files from: git diff --name-only main...HEAD | grep '\.go$']
-
-Run all quality gates in parallel and return combined analysis."
-```
-
-**The quality-analyzer agent automatically**:
+The agent automatically:
- Executes tests, linter, and code review in parallel (40-50% faster)
-- Normalizes outputs into common format
-- Identifies overlapping issues (same file:line from multiple sources)
-- Performs root cause analysis (why multiple issues occur together)
-- Prioritizes fixes by impact (issues resolved per fix)
-- Returns structured report with one of 4 statuses
-
-**Route based on agent status**:
-
-### Status: TEST_FAILURE β Enter Test Focus Mode
-
-**When**: Agent returns TEST_FAILURE status (tests failed)
+- Identifies overlapping issues with root cause analysis
+- Returns structured report with prioritized fixes
-**Action**: Focus exclusively on fixing tests before any quality analysis
+
+
+
+
+
+
-```
+
Loop until tests pass:
- 1. Display test failures from agent report
- 2. Analyze failure root cause
- 3. Apply fix to implementation or tests
- 4. Re-run quality-analyzer (mode: "full")
- 5. Check status:
- - Still TEST_FAILURE β Continue loop
- - ISSUES_FOUND or CLEAN_STATE β Exit Test Focus Mode, proceed with new status
+1. Analyze failure root cause
+2. Apply fix to implementation or tests
+3. Re-run quality-analyzer (mode: "full")
+4. Check status β continue or exit loop
Max 10 iterations. If stuck, ask user for guidance.
-```
-
-**Why Test Focus Mode**:
-- Tests are Gate 1 - nothing else matters if tests fail
-- Prevents wasting time on linter/review issues when code doesn't work
-- Ensures quality analysis runs on working code
-
-**After tests pass**: Re-run quality-analyzer and continue with new status
-
-### Status: CLEAN_STATE β Skip to Phase 5 (Documentation)
-
-**When**: Agent returns CLEAN_STATE status
-- β
Tests passed
-- β
Linter clean (0 errors)
-- β
Review clean (0 findings)
-
-**Action**: All quality gates passed! Skip fix loop, proceed directly to Phase 5 (Documentation)
-
-### Status: ISSUES_FOUND β Continue to Phase 3 (Fix Loop)
-
-**When**: Agent returns ISSUES_FOUND status
-- β
Tests passed
-- β Linter has errors OR β οΈ Review has findings
-
-**Action**: Display agent's combined report and proceed to Phase 3
-
-**Agent Report Contains**:
-- π Summary: Tests, linter, review status
-- π― Overlapping issues with root cause analysis
-- π Isolated issues (single source only)
-- π’ Prioritized fix order (by impact)
-
-**Example Report** (generated by quality-analyzer agent):
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-QUALITY ANALYSIS REPORT
-Mode: FULL
-Files analyzed: 8
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-π SUMMARY
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-Tests: β
PASS (coverage: 87%)
-Linter: β FAIL (5 errors)
-Review: β οΈ FINDINGS (8 issues: 0 bugs, 3 design, 4 readability, 1 polish)
-
-Total issues: 13 from 3 sources
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-OVERLAPPING ISSUES ANALYSIS
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-Found 3 locations with overlapping issues:
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β pkg/parser.go:45 - function Parse β
-β OVERLAPPING (4 issues): β
-β β
-β β οΈ Linter: Cognitive complexity 18 (>15) β
-β β οΈ Linter: Function length 58 statements (>50) β
-β π΄ Review: Mixed abstraction levels β
-β π΄ Review: Defensive null checking β
-β β
-β π― ROOT CAUSE: β
-β Function handles multiple responsibilities at β
-β different abstraction levels (parsing, validation, β
-β building result). β
-β β
-β Impact: HIGH (4 issues) | Complexity: MODERATE β
-β Priority: #1 CRITICAL β
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-PRIORITIZED FIX ORDER
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-Priority #1: pkg/parser.go:45 (4 issues, HIGH impact)
-Priority #2: pkg/validator.go:23 (3 issues, HIGH impact)
-Priority #3: pkg/handler.go:67 (2 issues, MEDIUM impact)
-
-Isolated issues: 6 (fix individually)
-
-Total fix targets: 3 overlapping groups + 6 isolated = 9 fixes
-
-STATUS: ISSUES_FOUND
-```
-
-### Status: TOOLS_UNAVAILABLE β Report Error
-
-**When**: Agent returns TOOLS_UNAVAILABLE status (missing tools)
-
-**Action**: Display agent report with missing tools and suggestions, ask user to install tools
-
-### Phase 3: Iterative Fix Loop
+
+
+
**For each prioritized fix** (from agent's report):
1. **Apply Fix**:
- - Invoke @refactoring skill with:
- * File and function to fix
- * All issues in that area (from agent's overlapping groups or isolated issues)
- * Root cause analysis from agent (if available)
- * Expected outcome
- - @refactoring applies appropriate patterns:
- * Early returns (reduce nesting)
- * Extract function (break complexity)
- * Storifying (uniform abstractions)
- * Extract type (create domain types)
- * Switch extraction (categorize cases)
- * Extract constant (remove magic numbers)
-
-2. **Verify Fix with Quality-Analyzer Agent (Incremental Mode)**:
-
- ```
- Task(subagent_type: "quality-analyzer")
+ - Invoke @refactoring skill with file, function, issues, and root cause
+ - @refactoring applies patterns: early returns, extract function, storifying, extract type, switch extraction, extract constant
- Prompt:
- "Re-analyze code quality after refactoring.
+2. **Verify Fix** (Incremental Mode):
+ - Re-run quality-analyzer with `mode: incremental`
+ - See `reference.md` β "Agent Prompt Templates" for prompt
+ - Agent returns delta report: fixed, remaining, new issues
- Mode: incremental
-
- Project commands:
- - Test: [PROJECT_TEST_COMMAND]
- - Lint: [PROJECT_LINT_COMMAND]
-
- Files to analyze (changed):
- [list files from: git diff --name-only HEAD~1 HEAD | grep '\.go$']
-
- Previous findings:
- [paste findings from previous quality-analyzer report]
-
- Run quality gates and return delta report (what changed)."
- ```
-
- **Agent returns delta report with status**:
- - β
Fixed: Issues resolved since last run
- - β οΈ Remaining: Issues still present
- - π New: Issues introduced by recent changes
-
-3. **Route Based on Agent Status**:
-
- **If status = TEST_FAILURE**:
- - β Enter Test Focus Mode (refactoring broke tests)
- - Loop until tests pass (same as Phase 2)
- - Continue with new status
-
- **If status = CLEAN_STATE**:
- - β All issues resolved! Break out of fix loop
- - Continue to Phase 4 (Documentation)
-
- **If status = ISSUES_FOUND**:
- - Check delta report for progress:
- * β
If issues were fixed β Continue to next fix
- * β οΈ If no progress β Analyze why, try different approach
- * π If new issues introduced β Fix them first
+3. **Route Based on Status**:
+ - `TEST_FAILURE` β Enter Test Focus Mode
+ - `CLEAN_STATE` β Break loop, go to Phase 4
+ - `ISSUES_FOUND` β Continue to next fix (or retry if no progress)
4. **Safety Limits**:
- Max 10 iterations per fix loop
- - IF stuck (no progress after 3 attempts):
- * Show current status and delta report
- * Ask user for guidance
- * User can review: `git diff`
-
-**Example Delta Report** (from quality-analyzer agent):
-```
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-QUALITY ANALYSIS DELTA REPORT
-Mode: INCREMENTAL
-Files re-analyzed: 1 (changed since last run)
-βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-π SUMMARY
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-Tests: β
PASS (coverage: 89% β)
-Linter: β
PASS (0 errors)
-Review: β
CLEAN (0 findings)
-
-β
Fixed: 4 issues from pkg/parser.go:45
-β οΈ Remaining: 0 issues
-π New: 0 issues introduced
-
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-RESOLUTION DETAILS
-βββββββββββββββββββββββββββββββββββββββββββββββββββ
-
-β
FIXED:
- pkg/parser.go:45 | Linter | Cognitive complexity (was 18, now 8)
- pkg/parser.go:45 | Linter | Function length (was 58, now 25)
- pkg/parser.go:45 | Review | Mixed abstraction levels (resolved)
- pkg/parser.go:45 | Review | Defensive null checking (resolved)
-
-STATUS: CLEAN_STATE β
-Ready to proceed with next fix or move to documentation phase.
-```
-
-**Loop until agent returns CLEAN_STATE**:
-- β
Tests pass
-- β
Linter clean
-- β
Review clean
-
-### Phase 4: Documentation
+ - If stuck after 3 attempts β show status, ask user
-Invoke @documentation skill:
+**Loop until agent returns CLEAN_STATE**.
+
+
+Invoke @documentation skill:
1. Add/update package-level godoc
-2. Add/update type-level documentation
-3. Add/update function documentation (WHY not WHAT)
-4. Add godoc testable examples (Example_* functions)
-5. IF last plan step:
- - Add feature documentation to docs/ folder
-
-**Verify**:
-- Run: `go doc -all ./...`
-- Ensure examples compile
-- Check documentation coverage
-
-### Phase 5: Commit Ready
-
-Generate comprehensive summary with suggested commit message.
-
-- Linter passes β
-- Tests pass with coverage β
-- Design review complete β
-- Documentation complete β
-- Present commit message suggestion
-
-## Output Format
-
-```
-π COMMIT READINESS SUMMARY
-
-β
Linter: Passed (0 issues)
-β
Tests: 95% coverage (3 new types, 15 test cases)
-β οΈ Design Review: 4 findings (see below)
-
-π― COMMIT SCOPE
-Modified:
-- user/service.go (+45, -12 lines)
-- user/repository.go (+23, -5 lines)
-
-Added:
-- user/user_id.go (new type: UserID)
-- user/email.go (new type: Email)
-
-Tests:
-- user/service_test.go (+120 lines)
-- user/user_id_test.go (new)
-- user/email_test.go (new)
-
-β οΈ DESIGN REVIEW FINDINGS
-
-π΄ DESIGN DEBT (Recommended to fix):
-- user/service.go:45 - Primitive obsession detected
- Current: func GetUserByID(id string) (*User, error)
- Better: func GetUserByID(id UserID) (*User, error)
- Why: Type safety, validation guarantee, prevents invalid IDs
- Fix: Use @code-designing to convert remaining string usages
-
-π‘ READABILITY DEBT (Consider fixing):
-- user/service.go:78 - Mixed abstraction levels in CreateUser
- Function mixes high-level steps with low-level validation details
- Why: Harder to understand flow at a glance
- Fix: Use @refactoring to extract validation helpers
-
-π’ POLISH OPPORTUNITIES:
-- user/repository.go:34 - Function naming could be more idiomatic
- SaveUser β Save (method receiver provides context)
-
-π BROADER CONTEXT:
-While reviewing user/service.go, noticed 3 more instances of string-based
-IDs throughout the file (lines 120, 145, 203). Consider refactoring the
-entire file to use UserID consistently for better type safety.
-
-π‘ SUGGESTED COMMIT MESSAGE
-Add self-validating UserID and Email types
-
-- Introduce UserID type with validation (prevents empty IDs)
-- Introduce Email type with RFC 5322 validation
-- Refactor CreateUser to use new types
-- Achieve 95% test coverage with real repository implementation
-
-Follows vertical slice architecture and primitive obsession principles.
-
-ββββββββββββββββββββββββββββββββββββββββ
-
-Would you like to:
-1. Commit as-is (ignore design findings)
-2. Fix design debt only (π΄), then commit
-3. Fix design + readability debt (π΄ + π‘), then commit
-4. Fix all findings (π΄ π‘ π’), then commit
-5. Refactor entire file (address broader context), then commit
-```
-
-## Workflow Control
-
-**Sequential Phases**: Each phase depends on previous phase completion
-- Phase 1: Design and implementation must complete before quality analysis
-- Phase 2: Quality analysis (via quality-analyzer agent) determines next phase
-- Phase 3: Fix loop continues until all issues resolved (agent returns CLEAN_STATE)
-- Phase 4: Documentation only after all quality gates pass
-- Phase 5: Commit ready summary presented to user
-
-**Status-Based Routing**: Agent determines workflow path
-- **TEST_FAILURE** β Test Focus Mode (fix tests, retry Phase 2)
-- **CLEAN_STATE** β Skip fix loop, go directly to documentation
-- **ISSUES_FOUND** β Enter fix loop (Phase 3)
-- **TOOLS_UNAVAILABLE** β Report error, ask user to install tools
-
-**Parallel Execution**: Phase 2 and fix verification run 3 tools simultaneously (40-50% faster)
-
-**Incremental Review**: After first run, agent only analyzes changed files for faster iteration
-
-## Integration with Other Skills and Agents
-
-This orchestrator **invokes** other skills and agents automatically:
-
-**Skills**:
-- @code-designing (Phase 1, if needed for type design)
-- @testing (Phase 1, principles applied)
-- @refactoring (Phase 3, when issues found)
-- @documentation (Phase 4, always)
-
-**Agents**:
-- quality-analyzer agent (Phase 2 and Phase 3 verification)
- - Internally delegates to go-code-reviewer agent for design analysis
- - Executes tests and linter in parallel
- - Returns intelligent combined reports with overlapping issue detection
-
-After committing, consider:
-- If feature complete β Feature fully documented in Phase 4
-- If more work needed β Run this workflow again for next commit
+2. Add/update type and function documentation (WHY not WHAT)
+3. Add godoc testable examples (Example_* functions)
+4. If last plan step β add feature documentation to docs/
+
+**Verify**: Run `go doc -all ./...` and ensure examples compile.
+
+
+
+Generate comprehensive summary. See `reference.md` β "Commit Readiness Output Format" for template.
+
+Present user with options:
+1. Commit as-is
+2. Fix design debt only, then commit
+3. Fix design + readability debt, then commit
+4. Fix all findings, then commit
+5. Refactor entire file, then commit
+
+
+
+
+
+
+
+
+
+
+
+
+**Skills invoked**:
+- @code-designing (Phase 1, if needed)
+- @testing (Phase 1)
+- @refactoring (Phase 3)
+- @documentation (Phase 4)
+
+**Agents invoked**:
+- `go-linter-driven-development:quality-analyzer` (Phase 2 and Phase 3 verification)
+ - Internally delegates to `go-linter-driven-development:go-code-reviewer` for design analysis
+
+**After committing**:
+- Feature complete β Already documented in Phase 4
+- More work needed β Run this workflow again for next commit
+
+
+
+Workflow is complete when ALL of the following are true:
+
+- [ ] Pre-flight check passed (Go project verified, commands discovered)
+- [ ] Phase 1 complete (tests written, code implemented)
+- [ ] Quality-analyzer returns `CLEAN_STATE`:
+ - [ ] Tests pass
+ - [ ] Linter passes (0 errors)
+ - [ ] Code review clean (0 findings)
+- [ ] Phase 4 complete (documentation added/updated)
+- [ ] Commit summary presented to user with options
+- [ ] User has chosen commit action (or deferred)
+
diff --git a/go-linter-driven-development/skills/linter-driven-development/reference.md b/go-linter-driven-development/skills/linter-driven-development/reference.md
index 8f5f639..852c897 100644
--- a/go-linter-driven-development/skills/linter-driven-development/reference.md
+++ b/go-linter-driven-development/skills/linter-driven-development/reference.md
@@ -1,38 +1,33 @@
-# Linter-Driven Development Reference
+
+This meta-orchestrator skill coordinates other skills. See individual skill reference files for detailed principles.
+
-This meta-orchestrator skill coordinates other skills. See individual skill reference files for detailed principles:
-
-## Phase-Specific References
-
-### Phase 1: Design
-See: **code-designing/reference.md**
+
+**Phase 1: Design** β See @code-designing skill
- Type design principles
- Primitive obsession prevention
- Self-validating types
- Vertical slice architecture
-### Phase 2: Implementation & Testing
-See: **testing/reference.md**
+**Phase 2: Implementation & Testing** β See @testing skill
- Testing principles
- Table-driven tests
- Testify suites
- Real implementations over mocks
-### Phase 3: Linter & Refactoring
-See: **refactoring/reference.md**
+**Phase 3: Linter & Refactoring** β See @refactoring skill
- Linter signal interpretation
- Refactoring patterns
- Complexity reduction strategies
-### Phase 4: Pre-Commit Review
-See: **pre-commit-review/reference.md**
+**Phase 4: Pre-Commit Review** β See @pre-commit-review skill
- Design principles checklist
- Debt categorization
- Review process
+
-## Linter Commands
-
-### Primary Command
+
+
```bash
task lintwithfix
```
@@ -40,61 +35,293 @@ Runs:
1. `go vet` - Static analysis
2. `golangci-lint fmt` - Format code
3. `golangci-lint run --fix` - Lint with auto-fix
+
-### Fallback (if no taskfile)
+
```bash
golangci-lint run --fix
```
+Use when no taskfile is available.
+
-### Configuration
+
- Config file: `.golangci.yaml` in project root
- Always use golangci-lint v2
- Reference: https://github.com/golangci/golangci-lint/blob/HEAD/.golangci.reference.yml
+
+
-## Linter Failure Signals
-
-### Cyclomatic Complexity
+
+
**Signal**: Function too complex (too many decision points)
**Action**: Extract functions, simplify logic flow
**Skill**: @refactoring
+
-### Cognitive Complexity
+
**Signal**: Function hard to understand (nested logic, mixed abstractions)
**Action**: Storifying, extract helpers, clarify abstraction levels
**Skill**: @refactoring
+
-### Maintainability Index
+
**Signal**: Code difficult to maintain
**Action**: Break into smaller pieces, improve naming, reduce coupling
**Skill**: @refactoring + potentially @code-designing
+
+
-## Coverage Targets
-
-### Leaf Types
+
+
- **Target**: 100% unit test coverage
- **Why**: Leaf types contain core logic, must be bulletproof
- **Test**: Only public API, use pkg_test package
+
-### Orchestrating Types
+
- **Target**: Integration test coverage
- **Why**: Test seams between components
- **Test**: Can overlap with leaf type coverage
+
+
-## Commit Readiness Criteria
-
+
All must be true:
-- β
Linter passes with 0 issues
-- β
Tests pass
-- β
Target coverage achieved (100% for leaf types)
-- β
Design review complete (advisory, but acknowledged)
+- Linter passes with 0 issues
+- Tests pass
+- Target coverage achieved (100% for leaf types)
+- Design review complete (advisory, but acknowledged)
+
+
+
+
+**Use for**: Initial quality analysis in Phase 2
+
+```
+Task(subagent_type: "go-linter-driven-development:quality-analyzer")
+
+Prompt:
+"Analyze code quality for this Go project.
+
+Mode: full
+
+Project commands:
+- Test: [PROJECT_TEST_COMMAND from Pre-Flight Check]
+- Lint: [PROJECT_LINT_COMMAND from Pre-Flight Check]
+
+Files to analyze:
+[list files from: git diff --name-only main...HEAD | grep '\.go$']
+
+Run all quality gates in parallel and return combined analysis."
+```
+
+
+
+**Use for**: Verification after each fix in Phase 3
+
+```
+Task(subagent_type: "go-linter-driven-development:quality-analyzer")
+
+Prompt:
+"Re-analyze code quality after refactoring.
+
+Mode: incremental
+
+Project commands:
+- Test: [PROJECT_TEST_COMMAND]
+- Lint: [PROJECT_LINT_COMMAND]
+
+Files to analyze (changed):
+[list files from: git diff --name-only HEAD~1 HEAD | grep '\.go$']
+
+Previous findings:
+[paste findings from previous quality-analyzer report]
+
+Run quality gates and return delta report (what changed)."
+```
+
+
+
+
+
+**Status**: ISSUES_FOUND
+
+This is what the quality-analyzer agent returns when issues are found:
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+QUALITY ANALYSIS REPORT
+Mode: FULL
+Files analyzed: 8
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+π SUMMARY
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Tests: β
PASS (coverage: 87%)
+Linter: β FAIL (5 errors)
+Review: β οΈ FINDINGS (8 issues: 0 bugs, 3 design, 4 readability, 1 polish)
+
+Total issues: 13 from 3 sources
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+OVERLAPPING ISSUES ANALYSIS
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Found 3 locations with overlapping issues:
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+β pkg/parser.go:45 - function Parse β
+β OVERLAPPING (4 issues): β
+β β
+β β οΈ Linter: Cognitive complexity 18 (>15) β
+β β οΈ Linter: Function length 58 statements (>50) β
+β π΄ Review: Mixed abstraction levels β
+β π΄ Review: Defensive null checking β
+β β
+β π― ROOT CAUSE: β
+β Function handles multiple responsibilities at β
+β different abstraction levels (parsing, validation, β
+β building result). β
+β β
+β Impact: HIGH (4 issues) | Complexity: MODERATE β
+β Priority: #1 CRITICAL β
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-## Next Steps After Commit
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+PRIORITIZED FIX ORDER
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Priority #1: pkg/parser.go:45 (4 issues, HIGH impact)
+Priority #2: pkg/validator.go:23 (3 issues, HIGH impact)
+Priority #3: pkg/handler.go:67 (2 issues, MEDIUM impact)
+
+Isolated issues: 6 (fix individually)
+
+Total fix targets: 3 overlapping groups + 6 isolated = 9 fixes
+
+STATUS: ISSUES_FOUND
+```
+
+
+
+**Status**: CLEAN_STATE (after fix)
+
+This is what the quality-analyzer agent returns in incremental mode:
+
+```
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+QUALITY ANALYSIS DELTA REPORT
+Mode: INCREMENTAL
+Files re-analyzed: 1 (changed since last run)
+βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+π SUMMARY
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+Tests: β
PASS (coverage: 89% β)
+Linter: β
PASS (0 errors)
+Review: β
CLEAN (0 findings)
+
+β
Fixed: 4 issues from pkg/parser.go:45
+β οΈ Remaining: 0 issues
+π New: 0 issues introduced
+
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+RESOLUTION DETAILS
+βββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+β
FIXED:
+ pkg/parser.go:45 | Linter | Cognitive complexity (was 18, now 8)
+ pkg/parser.go:45 | Linter | Function length (was 58, now 25)
+ pkg/parser.go:45 | Review | Mixed abstraction levels (resolved)
+ pkg/parser.go:45 | Review | Defensive null checking (resolved)
+
+STATUS: CLEAN_STATE β
+Ready to proceed with next fix or move to documentation phase.
+```
+
+
+
+
+**Use for**: Phase 5 summary output
+
+```
+π COMMIT READINESS SUMMARY
+
+β
Linter: Passed (0 issues)
+β
Tests: 95% coverage (3 new types, 15 test cases)
+β οΈ Design Review: 4 findings (see below)
+
+π― COMMIT SCOPE
+Modified:
+- user/service.go (+45, -12 lines)
+- user/repository.go (+23, -5 lines)
+
+Added:
+- user/user_id.go (new type: UserID)
+- user/email.go (new type: Email)
+
+Tests:
+- user/service_test.go (+120 lines)
+- user/user_id_test.go (new)
+- user/email_test.go (new)
+
+β οΈ DESIGN REVIEW FINDINGS
+
+π΄ DESIGN DEBT (Recommended to fix):
+- user/service.go:45 - Primitive obsession detected
+ Current: func GetUserByID(id string) (*User, error)
+ Better: func GetUserByID(id UserID) (*User, error)
+ Why: Type safety, validation guarantee, prevents invalid IDs
+ Fix: Use @code-designing to convert remaining string usages
+
+π‘ READABILITY DEBT (Consider fixing):
+- user/service.go:78 - Mixed abstraction levels in CreateUser
+ Function mixes high-level steps with low-level validation details
+ Why: Harder to understand flow at a glance
+ Fix: Use @refactoring to extract validation helpers
+
+π’ POLISH OPPORTUNITIES:
+- user/repository.go:34 - Function naming could be more idiomatic
+ SaveUser β Save (method receiver provides context)
+
+π BROADER CONTEXT:
+While reviewing user/service.go, noticed 3 more instances of string-based
+IDs throughout the file (lines 120, 145, 203). Consider refactoring the
+entire file to use UserID consistently for better type safety.
+
+π‘ SUGGESTED COMMIT MESSAGE
+Add self-validating UserID and Email types
+
+- Introduce UserID type with validation (prevents empty IDs)
+- Introduce Email type with RFC 5322 validation
+- Refactor CreateUser to use new types
+- Achieve 95% test coverage with real repository implementation
+
+Follows vertical slice architecture and primitive obsession principles.
+
+ββββββββββββββββββββββββββββββββββββββββ
+
+Would you like to:
+1. Commit as-is (ignore design findings)
+2. Fix design debt only (π΄), then commit
+3. Fix design + readability debt (π΄ + π‘), then commit
+4. Fix all findings (π΄ π‘ π’), then commit
+5. Refactor entire file (address broader context), then commit
+```
+
-### Feature Complete?
+
+
β Invoke @documentation skill to create feature docs
+
-### More Work Needed?
+
β Run @linter-driven-development again for next commit
+
-### Found Broader Issues During Review?
+
β Create new task to address technical debt
+
+
diff --git a/go-linter-driven-development/skills/pre-commit-review/SKILL.md b/go-linter-driven-development/skills/pre-commit-review/SKILL.md
index ad0a555..f1a23c5 100644
--- a/go-linter-driven-development/skills/pre-commit-review/SKILL.md
+++ b/go-linter-driven-development/skills/pre-commit-review/SKILL.md
@@ -1,42 +1,70 @@
---
name: pre-commit-review
-description: ADVISORY validation of code against design principles that linters cannot enforce. Use after linter passes and tests pass to validate design quality. Categorizes findings as Design Debt, Readability Debt, or Polish Opportunities. Does NOT block commits.
+description: |
+ ADVISORY validation of code against design principles that linters cannot enforce.
+ Loaded by go-code-reviewer agent for design analysis guidance. Also invoked by @refactoring (after pattern application).
+ Can be manually invoked for standalone code review.
+ Categorizes findings as Design Debt, Readability Debt, or Polish Opportunities. Does NOT block commits.
---
-# Pre-Commit Design Review
-
-Expert design analysis that detects issues linters can't catch. Returns detailed report to caller with categorized findings and fix recommendations.
-
-## What This Skill Does
+
+Expert design analysis that detects issues linters can't catch.
+Returns detailed report to caller with categorized findings and fix recommendations.
**Pure Analysis & Reporting** - Generates report, doesn't fix anything or invoke skills.
-### Input
+**Reference**: See `reference.md` for complete detection checklist with examples.
+**Examples**: See `examples.md` for real-world review scenarios.
+
+
+
+1. **Read files** under review (all staged or specific files)
+2. **Apply design principles** checklist from reference.md (LLM reasoning)
+3. **Search usage patterns** with Grep tool
+4. **Categorize findings**: Bugs, Design Debt, Readability Debt, Polish
+5. **Generate structured report** with file:line locations and fix recommendations
+6. **Return report** to caller (no fixes, no skill invocations)
+
+
+
+
- Files to review (specific files or all staged changes)
- Review mode: `full` (first run) or `incremental` (subsequent runs)
- Previous findings (optional, for incremental mode)
- Context (invoked by refactoring, orchestrator, subagent, or user)
+
-### Output
+
+
-### Invocation Modes
-
-**1. Direct Skill Invocation** (User or Orchestrator)
+
+
- Full control, can invoke other skills
- Can make changes based on findings
- Interactive mode with user feedback
+
-**2. Subagent Mode** (Task tool with go-code-reviewer)
+
- Read-only analysis, returns report only
- Cannot invoke other skills
- Used for parallel execution by orchestrator
- Designed for speed and focused analysis
+
+
-### What Reviewer Detects (That Linters Can't)
+
+1. **go-code-reviewer agent** - Loads this skill for design analysis guidance during parallel quality analysis
+2. **@refactoring skill** - After applying patterns, validates design quality remains high
+3. **User** - Manual code review before commit
+
+
+
+**What Reviewer Detects (That Linters Can't):**
- Primitive obsession (with juiciness scoring)
- Unstorified functions (mixed abstraction levels)
- Missing domain concepts (implicit types that should be explicit)
@@ -47,47 +75,41 @@ Expert design analysis that detects issues linters can't catch. Returns detailed
- Design bugs (nil deref, ignored errors, resource leaks)
- Test quality (weak assertions, missing use cases, mock overuse, conditionals in tests)
-**See [reference.md](./reference.md) for complete detection checklist with examples**
-
-## Who Invokes This Skill
-
-1. **@refactoring skill** - After applying patterns, validates design quality remains high
-2. **@linter-driven-development** - Phase 4, checks design quality after linter passes
-3. **User** - Manual code review before commit
+**Division of Labor:**
+- **Linter handles**: Complexity metrics, line counts, formatting, syntax
+- **Reviewer handles**: Design patterns, domain modeling, conceptual issues
-## Workflow
+See [reference.md](./reference.md) for complete detection checklist with examples.
+
-### Full Review Mode (First Run)
+
-```
+
1. Read all files under review (using Read tool)
2. Apply design principles checklist from reference.md (LLM reasoning)
3. Search for usage patterns across codebase (using Grep tool)
4. Categorize findings:
- π Bugs (nil deref, ignored errors, resource leaks)
- π΄ Design Debt (types, architecture, validation)
- π‘ Readability Debt (abstraction, flow, clarity)
- π’ Polish (naming, docs, minor improvements)
+ - Bugs (nil deref, ignored errors, resource leaks)
+ - Design Debt (types, architecture, validation)
+ - Readability Debt (abstraction, flow, clarity)
+ - Polish (naming, docs, minor improvements)
5. Generate structured report with recommendations
6. Return report to caller (doesn't invoke other skills or make fixes)
-```
-
-### Incremental Review Mode (Subsequent Runs)
+
+
Used after fixes have been applied to verify resolution and detect new issues.
-```
1. Read ONLY changed files since last review (using git diff)
2. Compare against previous findings:
- - Mark resolved issues as β
Fixed
+ - Mark resolved issues as Fixed
- Identify issues that still exist
3. Analyze changed code for NEW issues introduced by fixes
4. Generate delta report:
- - β
Fixed: Issues from previous run that are now resolved
- - β οΈ Remaining: Issues that still need attention
- - π New: Issues introduced by recent changes
+ - Fixed: Issues from previous run that are now resolved
+ - Remaining: Issues that still need attention
+ - New: Issues introduced by recent changes
5. Return concise delta report (not full analysis)
-```
**When to Use Incremental Mode:**
- After @refactoring skill applies fixes
@@ -98,9 +120,11 @@ Used after fixes have been applied to verify resolution and detect new issues.
- Faster execution (only analyzes changed files)
- Clear feedback on what was fixed vs what remains
- Detects regressions introduced by fixes
+
-## Detection Approach
+
+
**LLM-Powered Analysis** (not AST parsing or metrics calculation):
The reviewer reads code like a senior developer and applies design principles:
@@ -110,23 +134,17 @@ The reviewer reads code like a senior developer and applies design principles:
- Pattern matches against anti-patterns
- Counts occurrences and calculates juiciness scores
- Generates findings with specific locations and fix guidance
+
-**Division of Labor:**
-- **Linter handles**: Complexity metrics, line counts, formatting, syntax
-- **Reviewer handles**: Design patterns, domain modeling, conceptual issues
-
-## Report Format
-
-### Full Report (First Run)
+
+
```
π CODE REVIEW REPORT
Scope: [files reviewed]
Mode: FULL
-βββββββββββββββββββββββββββββββββββββββββββββ
SUMMARY
-βββββββββββββββββββββββββββββββββββββββββββββ
Total findings: 18
π Bugs: 2 (fix immediately)
@@ -140,17 +158,15 @@ Estimated fix effort: 3.5 hours
[Recommendations by priority]
[Skills to use for fixes]
```
+
-### Incremental Report (Subsequent Runs)
-
+
```
π CODE REVIEW DELTA REPORT
Scope: [changed files only]
Mode: INCREMENTAL
-βββββββββββββββββββββββββββββββββββββββββββββ
SUMMARY
-βββββββββββββββββββββββββββββββββββββββββββββ
β
Fixed: 4 (resolved from previous run)
β οΈ Remaining: 2 (still need attention)
@@ -158,9 +174,9 @@ SUMMARY
[Detailed delta findings]
```
+
-### Structured Output for Orchestrator Parsing
-
+
When invoked as subagent for combined analysis, output follows strict format:
```
@@ -189,56 +205,50 @@ file:line | Issue description | Why it matters | Fix strategy | Effort: [Trivial
**file:line Format:** Must be exact for orchestrator to correlate with linter errors
- Example: `pkg/parser.go:45`
- NOT: `parser.go line 45` or `pkg/parser.go (line 45)`
+
-**See [examples.md](./examples.md) for complete report examples**
-
-## What This Skill Does NOT Do
+
-- β Invoke other skills (@refactoring, @code-designing, @testing)
-- β Fix anything or make code changes
-- β Make decisions on behalf of user
-- β Parse AST or calculate complexity metrics (linter does this)
-- β Run linter (caller does this)
-- β Iterate or loop (caller decides whether to re-invoke)
-- β Block commits (findings are advisory)
+
+This skill MUST NOT:
+- Invoke other skills (@refactoring, @code-designing, @testing)
+- Fix anything or make code changes
+- Make decisions on behalf of user
+- Parse AST or calculate complexity metrics (linter does this)
+- Run linter (caller does this)
+- Iterate or loop (caller decides whether to re-invoke)
+- Block commits (findings are advisory)
+
-## Integration with Other Skills
+
-### Invoked by @refactoring
-```
+
Refactoring completes β invoke reviewer β analyze report:
- Bugs found? β Fix immediately, re-run linter
- Design debt found? β Apply another refactoring pattern
- All clean? β Return success to orchestrator
-```
-
-### Invoked by @linter-driven-development
-```
-Phase 4 (after linter passes):
-1. Invoke reviewer on all staged changes
-2. Receive categorized report
-3. Present findings to user with options:
- - Commit as-is (accept debt knowingly)
- - Fix critical issues only (bugs + design debt)
- - Fix all recommended (bugs + design + readability)
- - Fix everything (including polish)
-4. Based on user choice:
- - Invoke @refactoring or @code-designing for chosen fixes
- - Return to Phase 3 (linter loop)
- - Iterate until user satisfied
-```
-
-### Invoked by User
-```
+
+
+
+During Phase 2 (Parallel Quality Analysis):
+1. go-code-reviewer agent automatically loads this skill for guidance
+2. Agent applies detection checklist from this skill
+3. Agent returns structured report to quality-analyzer
+4. quality-analyzer combines with linter/test results
+5. Orchestrator routes based on combined findings
+
+
+
Manual review request:
1. User invokes: @pre-commit-review on path/to/file.go
2. Receive detailed report
3. User decides how to proceed
4. User may invoke @refactoring or @code-designing for fixes
-```
+
-## Review Scope
+
+
**Primary Scope**: Changed code in commit
- All modified lines
- All new files
@@ -248,75 +258,75 @@ Manual review request:
- Entire files containing modifications
- Flag patterns/issues outside commit scope (in BROADER CONTEXT section)
- Suggest broader refactoring opportunities if valuable
+
-## Advisory Nature
-
+
**This review does NOT block commits.**
Purpose:
-- β
Provide visibility into design quality
-- β
Offer concrete improvement suggestions with examples
-- β
Help maintain coding principles
-- β
Guide refactoring decisions
+- Provide visibility into design quality
+- Offer concrete improvement suggestions with examples
+- Help maintain coding principles
+- Guide refactoring decisions
Caller (or user) decides:
- Commit as-is (accept debt knowingly)
- Fix critical debt before commit (bugs, major design issues)
- Fix all debt before commit (comprehensive cleanup)
- Expand scope to broader refactor (when broader context issues found)
+
-## Finding Categories
-
-Findings are categorized by technical debt type and severity:
+
-### π Bugs
+
**Will cause runtime failures or correctness issues**
- Nil dereferences, ignored errors, resource leaks
- Invalid nil returns, race conditions
- Fix immediately before any other work
+
-### π΄ Design Debt
+
**Will cause pain when extending/modifying code**
- Primitive obsession, missing domain types
- Non-self-validating types
- Wrong architecture (horizontal vs vertical)
- Fix before commit recommended
+
-### π‘ Readability Debt
+
**Makes code harder to understand and work with**
- Mixed abstraction levels, not storified
- Functions too long or complex
- Poor naming, unclear intent
- Fix improves team productivity
+
-### π’ Polish Opportunities
+
**Minor improvements for consistency and quality**
- Non-idiomatic naming, missing examples
- Comment improvements, minor refactoring
- Low priority, nice to have
-
-**See [reference.md](./reference.md) for detailed principles and examples for each category**
-
-## Key Capabilities
-
-**Detects 8 Issue Categories:**
-1. Primitive Obsession - with juiciness scoring algorithm
-2. Storifying - detects mixed abstraction levels
-3. Missing Domain Concepts - identifies implicit types
-4. Self-Validating Types - finds defensive code patterns
-5. Comment Quality - analyzes what vs why
-6. File Structure - checks size and responsibility boundaries
-7. Testing Approach - validates test structure and quality
-8. Design Bugs - catches common runtime issues
-
-**For complete detection patterns and examples, see [reference.md](./reference.md)**
-**For real-world review scenarios, see [examples.md](./examples.md)**
-
-## Integration with Orchestrator
-
-This skill is automatically invoked by @linter-driven-development workflow:
-- **Phase 4**: Design review after linter passes
-- **Iterative**: Re-invoked after fixes until clean or user accepts debt
-- **Advisory**: Never blocks, always presents options
-
-See [linter-driven-development workflow](../linter-driven-development/SKILL.md) for complete flow.
+
+
+See [reference.md](./reference.md) for detailed principles and examples for each category.
+
+
+
+**Code Quality Analysis Performed:**
+- [ ] Read every function - does it read like a story? (single abstraction level)
+- [ ] Checked all functions for mixed abstraction levels (storifying needed?)
+- [ ] Evaluated primitives for primitive obsession (juiciness test applied)
+- [ ] Assessed types for self-validation (defensive code in methods?)
+- [ ] Reviewed comment quality (explaining WHY not WHAT?)
+- [ ] Checked file structure (too long? too many types?)
+- [ ] Searched for missing domain concepts (implicit types that should be explicit)
+- [ ] Validated test quality (weak assertions? conditionals in tests? mock overuse?)
+- [ ] Scanned for design bugs (nil deref, ignored errors, resource leaks)
+
+**Report Quality:**
+- [ ] All findings categorized by severity (Bugs, Design Debt, Readability Debt, Polish)
+- [ ] Each finding includes: file:line, issue, why it matters, fix strategy, effort estimate
+- [ ] Structured format parseable by orchestrator
+- [ ] Clear distinction between bugs (fix immediately) and advisory findings
+- [ ] Incremental mode accurately tracks fixed, remaining, and new issues
+
diff --git a/go-linter-driven-development/skills/refactoring/SKILL.md b/go-linter-driven-development/skills/refactoring/SKILL.md
index c46328c..b03052f 100644
--- a/go-linter-driven-development/skills/refactoring/SKILL.md
+++ b/go-linter-driven-development/skills/refactoring/SKILL.md
@@ -1,13 +1,30 @@
---
name: refactoring
-description: Linter-driven refactoring patterns to reduce complexity and improve code quality. Use when linter fails with complexity issues (cyclomatic, cognitive, maintainability) or when code feels hard to read/maintain. Applies storifying, type extraction, and function extraction patterns.
+description: |
+ Linter-driven refactoring patterns to reduce complexity and improve code quality.
+ Use when linter fails with complexity issues (cyclomatic, cognitive, maintainability) or when code feels hard to read/maintain.
+ Applies storifying, type extraction, and function extraction patterns.
---
-# Refactoring
-
+
Linter-driven refactoring patterns to reduce complexity and improve code quality.
+Operates autonomously - no user confirmation needed during execution.
+
+**Reference**: See `reference.md` for complete decision tree and all patterns.
+**Examples**: See `examples.md` for real-world refactoring case studies.
+
+
+
+1. **Receive linter failures** from @linter-driven-development
+2. **Analyze root cause** - Does it read like a story? Can it be broken down?
+3. **Apply patterns** in priority order (early returns β extract function β storifying β extract type)
+4. **Verify** - Re-run linter automatically
+5. **Iterate** until linter passes
-## When to Use
+**IMPORTANT**: This skill operates autonomously - no user confirmation needed.
+
+
+
- **Automatically invoked** by @linter-driven-development when linter fails
- **Automatically invoked** by @pre-commit-review when design issues detected
- **Complexity failures**: cyclomatic, cognitive, maintainability index
@@ -16,36 +33,32 @@ Linter-driven refactoring patterns to reduce complexity and improve code quality
- Functions > 50 LOC or nesting > 2 levels
- Mixed abstraction levels in functions
- Manual invocation when code feels hard to read/maintain
+
-**IMPORTANT**: This skill operates autonomously - no user confirmation needed during execution
-
-## Learning Resources
-
+
Choose your learning path:
- **Quick Start**: Use the patterns below for common refactoring cases
- **Complete Reference**: See [reference.md](./reference.md) for full decision tree and all patterns
- **Real-World Examples**: See [examples.md](./examples.md) to learn the refactoring thought process
- [Example 1](./examples.md#example-1-storifying-mixed-abstractions-and-extracting-logic-into-leaf-types): Storifying and extracting a single leaf type
- [Example 2](./examples.md#example-2-primitive-obsession-with-multiple-types-and-storifying-switch-statements): Primitive obsession with multiple types and switch elimination
+
-## Analysis Phase (Automatic)
+
+Before applying any refactoring patterns, automatically analyze the context:
-Before applying any refactoring patterns, the skill automatically analyzes the context:
-
-### System Context Analysis
-```
+
AUTOMATICALLY ANALYZE:
1. Find all callers of the failing function
2. Identify which flows/features depend on it
3. Determine primary responsibility
4. Check for similar functions revealing patterns
5. Spot potential refactoring opportunities
-```
+
-### Type Discovery
+
Proactively identify hidden types in the code:
-```
POTENTIAL TYPES TO DISCOVER:
1. Data being parsed from strings β Parse* types
Example: ParseCommandResult(), ParseLogEntry()
@@ -61,18 +74,19 @@ POTENTIAL TYPES TO DISCOVER:
5. Repeated string manipulation β Types with methods
Example: FilePath with Dir(), Base(), Ext()
-```
+
-### Analysis Output
+
The analysis produces a refactoring plan identifying:
- Function's role in the system
- Potential domain types to extract
- Recommended refactoring approach
- Expected complexity reduction
+
+
-## Refactoring Signals
-
-### Linter Failures
+
+
**Complexity Issues:**
- **Cyclomatic Complexity**: Too many decision points β Extract functions, simplify logic
- **Cognitive Complexity**: Hard to understand β Storifying, reduce nesting
@@ -87,51 +101,22 @@ The analysis produces a refactoring plan identifying:
- **dupl**: Code duplication β Extract common logic/types
- **goconst**: Magic strings/numbers β Extract constants or types
- **ineffassign**: Ineffective assignments β Simplify logic
+
-### Code Smells
+
- Functions > 50 LOC
- Nesting > 2 levels
- Mixed abstraction levels
- Unclear flow/purpose
- Primitive obsession
- Global variable access scattered throughout code
+
+
-## Workflow (Automatic)
-
-### 1. Receive Linter Failures
-Automatically receive failures from @linter-driven-development:
-```
-user/service.go:45:1: cyclomatic complexity 15 of func `CreateUser` is high (> 10)
-user/handler.go:23:1: cognitive complexity 25 of func `HandleRequest` is high (> 15)
-```
-
-### 2. Automatic Root Cause Analysis
-The skill automatically diagnoses each failure:
-- Does this code read like a story? β Apply storifying
-- Can this be broken into smaller pieces? β Extract functions/types
-- Does logic run on primitives? β Check for primitive obsession
-- Is function long due to switch statement? β Extract case handlers
-
-### 3. Automatic Pattern Application
-Applies patterns in priority order without user intervention:
-- **Early Returns**: Try first (least invasive)
-- **Extract Function**: Break up complexity
-- **Storifying**: Improve abstraction levels
-- **Extract Type**: Create domain types (if juicy)
-- **Switch Extraction**: Categorize cases
-
-### 4. Automatic Verification Loop
-- Re-run linter automatically
-- If still failing, try next pattern
-- Continue until linter passes
-- Report final results
-
-## Automation Flow
-
+
This skill operates completely autonomously once invoked:
-### Automatic Iteration Loop
-```
+
AUTOMATED PROCESS:
1. Receive trigger:
- From @linter-driven-development (linter failures)
@@ -144,77 +129,65 @@ AUTOMATED PROCESS:
5. If patterns exhausted and still failing:
- Report what was tried
- Suggest file splitting or architectural changes
-```
-
-### Pattern Priority Order
-Apply patterns based on failure type:
+
+
**For Complexity Failures** (cyclomatic, cognitive, maintainability):
-```
1. Early Returns β Reduce nesting quickly
2. Extract Function β Break up long functions
3. Storifying β Improve abstraction levels
4. Extract Type β Create domain types (only if "juicy")
5. Switch Extraction β Categorize switch cases
-```
**For Architectural Failures** (noglobals, singletons):
-```
1. Dependency Rejection β Incremental bottom-up approach
2. Extract Type with dependency injection
3. Push global access up call chain one level
4. Iterate until globals only at entry points (main, handlers)
-```
**For Design Smells** (dupl, goconst):
-```
1. Extract Type β For repeated values or validation
2. Extract Function β For code duplication
3. Extract Constant β For magic strings/numbers
-```
+
-### No Manual Intervention
+
- **NO** asking for confirmation between patterns
- **NO** waiting for user input
- **NO** manual linter runs
- **AUTOMATIC** progression through patterns
- **ONLY** report results at the end
+
+
-## Refactoring Patterns
-
-### Pattern 1: Storifying (Mixed Abstractions)
-**Signal**: Function mixes high-level steps with low-level details
+
+
```go
-// β Before - Mixed abstractions
+// BEFORE - Mixed abstractions
func ProcessOrder(order Order) error {
// Validation
if order.ID == "" {
return errors.New("invalid")
}
-
// Low-level DB setup
db, err := sql.Open("postgres", connStr)
if err != nil { return err }
defer db.Close()
-
// SQL construction
query := "INSERT INTO..."
// ... many lines
-
return nil
}
-// β
After - Story-like
+// AFTER - Story-like
func ProcessOrder(order Order) error {
if err := validateOrder(order); err != nil {
return err
}
-
if err := saveToDatabase(order); err != nil {
return err
}
-
return notifyCustomer(order)
}
@@ -222,35 +195,32 @@ func validateOrder(order Order) error { /* ... */ }
func saveToDatabase(order Order) error { /* ... */ }
func notifyCustomer(order Order) error { /* ... */ }
```
+
-### Pattern 2: Extract Type (Primitive Obsession)
-**Signal**: Complex logic operating on primitives OR unstructured data needing organization
-
-#### Juiciness Test v2 - When to Create Types
-
+
+
**BEHAVIORAL JUICINESS** (rich behavior):
-- β
Complex validation rules (regex, ranges, business rules)
-- β
Multiple meaningful methods (β₯2 methods)
-- β
State transitions or transformations
-- β
Format conversions (different representations)
+- Complex validation rules (regex, ranges, business rules)
+- Multiple meaningful methods (β₯2 methods)
+- State transitions or transformations
+- Format conversions (different representations)
**STRUCTURAL JUICINESS** (organizing complexity):
-- β
Parsing unstructured data into fields
-- β
Grouping related data that travels together
-- β
Making implicit structure explicit
-- β
Replacing map[string]interface{} with typed fields
+- Parsing unstructured data into fields
+- Grouping related data that travels together
+- Making implicit structure explicit
+- Replacing map[string]interface{} with typed fields
**USAGE JUICINESS** (simplifies code):
-- β
Used in multiple places
-- β
Significantly simplifies calling code
-- β
Makes tests cleaner and more focused
+- Used in multiple places
+- Significantly simplifies calling code
+- Makes tests cleaner and more focused
**Score**: Need "yes" in at least ONE category to create the type
-
-#### Examples of Juicy vs Non-Juicy Types
+
```go
-// β NOT JUICY - Don't create type
+// NOT JUICY - Don't create type
func ValidateUserID(id string) error {
if id == "" {
return errors.New("empty id")
@@ -259,7 +229,7 @@ func ValidateUserID(id string) error {
}
// Just use: if userID == ""
-// β
JUICY (Behavioral) - Complex validation
+// JUICY (Behavioral) - Complex validation
type Email string
func ParseEmail(s string) (Email, error) {
@@ -277,91 +247,61 @@ func ParseEmail(s string) (Email, error) {
func (e Email) Domain() string { /* extract domain */ }
func (e Email) LocalPart() string { /* extract local */ }
-func (e Email) String() string { return string(e) }
-// β
JUICY (Structural) - Parsing complex data
+// JUICY (Structural) - Parsing complex data
type CommandResult struct {
FailedFiles []string
SuccessFiles []string
Message string
ExitCode int
- Warnings []string
}
func ParseCommandResult(output string) (CommandResult, error) {
// Parse unstructured output into structured fields
- // Making implicit structure explicit
}
-
-// β
JUICY (Mixed) - Both behavior and structure
-type ServiceEndpoint struct {
- host string
- port Port
-}
-
-func ParseEndpoint(s string) (ServiceEndpoint, error) {
- // Parse "host:port/path" format
-}
-
-func (e ServiceEndpoint) URL() string { }
-func (e ServiceEndpoint) IsSecure() bool { }
-func (e ServiceEndpoint) WithPath(path string) string { }
```
-**β οΈ Warning Signs of Over-Engineering:**
+**Warning Signs of Over-Engineering:**
- Type with only one trivial method
- Simple validation (just empty check)
- Type that's just a wrapper without behavior
- Good variable naming would be clearer
-**β See [Example 2](./examples.md#first-refactoring-attempt-the-over-abstraction-trap)** for complete case study.
-
-### Pattern 3: Extract Function (Long Functions)
-**Signal**: Function > 50 LOC or multiple responsibilities
+See [Example 2](./examples.md#first-refactoring-attempt-the-over-abstraction-trap) for complete case study.
+
+
```go
-// β Before - Long function
+// BEFORE - Long function
func CreateUser(data map[string]interface{}) error {
// Validation (15 lines)
- // ...
-
// Database operations (20 lines)
- // ...
-
// Email notification (10 lines)
- // ...
-
// Logging (5 lines)
- // ...
-
return nil
}
-// β
After - Extracted functions
+// AFTER - Extracted functions
func CreateUser(data map[string]interface{}) error {
user, err := validateAndParseUser(data)
if err != nil {
return err
}
-
if err := saveUser(user); err != nil {
return err
}
-
if err := sendWelcomeEmail(user); err != nil {
return err
}
-
logUserCreation(user)
return nil
}
```
+
-### Pattern 4: Early Returns (Deep Nesting)
-**Signal**: Nesting > 2 levels
-
+
```go
-// β Before - Deeply nested
+// BEFORE - Deeply nested
func ProcessItem(item Item) error {
if item.IsValid() {
if item.IsReady() {
@@ -379,30 +319,26 @@ func ProcessItem(item Item) error {
}
}
-// β
After - Early returns
+// AFTER - Early returns
func ProcessItem(item Item) error {
if !item.IsValid() {
return errors.New("invalid")
}
-
if !item.IsReady() {
return errors.New("not ready")
}
-
if !item.HasPermission() {
return errors.New("no permission")
}
-
// Process
return nil
}
```
+
-### Pattern 5: Switch Extraction (Long Switch)
-**Signal**: Switch statement with complex cases
-
+
```go
-// β Before - Long switch in one function
+// BEFORE - Long switch in one function
func HandleRequest(reqType string, data interface{}) error {
switch reqType {
case "create":
@@ -417,7 +353,7 @@ func HandleRequest(reqType string, data interface{}) error {
return nil
}
-// β
After - Extracted handlers
+// AFTER - Extracted handlers
func HandleRequest(reqType string, data interface{}) error {
switch reqType {
case "create":
@@ -435,10 +371,9 @@ func handleCreate(data interface{}) error { /* ... */ }
func handleUpdate(data interface{}) error { /* ... */ }
func handleDelete(data interface{}) error { /* ... */ }
```
+
-### Pattern 6: Dependency Rejection (Architectural Refactoring)
-**Signal**: noglobals linter fails OR global/singleton usage detected
-
+
**Goal**: Create "islands of clean code" by incrementally pushing dependencies up the call chain
**Strategy**: Work from bottom-up, rejecting dependencies one level at a time
@@ -448,15 +383,14 @@ func handleDelete(data interface{}) error { /* ... */ }
- Push global access up one level
- Repeat until global only at entry points
-**Quick Example**:
```go
-// β Before - Global accessed deep in code
+// BEFORE - Global accessed deep in code
func PublishEvent(event Event) error {
conn, err := nats.Connect(env.Configs.NATsAddress)
// ... complex logic
}
-// β
After - Dependency rejected up one level
+// AFTER - Dependency rejected up one level
type EventPublisher struct {
natsAddress string // injected, not global
}
@@ -484,10 +418,12 @@ func SetupMessaging() *EventPublisher {
- **Pragmatic**: Accept globals at entry points (main, handlers)
- **Testability**: Each extracted type is an island (testable in isolation)
-**β See [Example 3](./examples.md#example-3-dependency-rejection-pattern) for complete case study with config access patterns**
+See [Example 3](./examples.md#example-3-dependency-rejection-pattern) for complete case study.
+
-## Refactoring Decision Tree
+
+
When linter fails, ask these questions (see reference.md for details):
1. **Does this read like a story?**
@@ -506,10 +442,9 @@ When linter fails, ask these questions (see reference.md for details):
5. **Are there deeply nested if/else?**
- Yes β Use early returns or extract functions
+
-## Testing Integration
-
-### Automatic Test Creation
+
When creating new types or extracting functions during refactoring:
**ALWAYS invoke @testing skill** to write tests for:
@@ -518,13 +453,12 @@ When creating new types or extracting functions during refactoring:
- **Extracted functions**: New functions created during refactoring
- **Parse functions**: Functions that transform unstructured data
-### Island of Clean Code Definition
-
+
A type is an "island of clean code" if:
-- β
Dependencies are explicit (injected via constructor)
-- β
No global or static dependencies
-- β
Can be tested in isolation
-- β
Has 100% testable public API
+- Dependencies are explicit (injected via constructor)
+- No global or static dependencies
+- Can be tested in isolation
+- Has 100% testable public API
**Examples of testable islands:**
- `NATSClient` with injected `natsAddress` string (no other dependencies)
@@ -533,40 +467,25 @@ A type is an "island of clean code" if:
- `OrderService` with injected `Repository` and `EventPublisher` (all testable)
**Note**: Islands can depend on other value objects and still be isolated!
+
-### Workflow
-```
+
REFACTORING β TESTING:
1. Extract type during refactoring
2. Immediately invoke @testing skill
-3. @testing skill writes appropriate tests:
- - Table-driven tests for simple scenarios
- - Testify suites for complex infrastructure
- - Integration tests for orchestrating types
+3. @testing skill writes appropriate tests
4. Verify tests pass
5. Continue refactoring
-```
-
-### Testing Delegation
-- **Refactoring skill**: Makes code testable (creates islands)
-- **@testing skill**: Writes all tests (structure, patterns, coverage)
-
-**β See @testing skill for test structure, patterns, and guidelines**
-
-## Stopping Criteria
-
-### When to Stop Refactoring
+
+
+
**STOP when ALL of these are met:**
-```
-β
Linter passes
-β
All functions < 50 LOC
-β
Nesting β€ 2 levels
-β
Code reads like a story
-β
No more "juicy" abstractions to extract
-```
-
-### Don't Over-Refactor
+- Linter passes
+- All functions < 50 LOC
+- Nesting β€ 2 levels
+- Code reads like a story
+- No more "juicy" abstractions to extract
**Warning Signs of Over-Engineering:**
- Creating types with only one method
@@ -576,184 +495,105 @@ REFACTORING β TESTING:
- Diminishing returns on complexity reduction
**Pragmatic Approach:**
-```
IF linter passes AND code is readable:
STOP - Don't extract more
EVEN IF you could theoretically extract more:
STOP - Avoid abstraction bloat
-```
+
-### Example Stopping Decision
+
```
-Current State:
-- Function: 45 LOC (was 120) β
-- Complexity: 8 (was 25) β
-- Nesting: 2 levels (was 4) β
-- Created 2 juicy types (Email, PhoneNumber) β
-
-Could extract UserID type but:
-- Only validation is "not empty" β
-- No other methods needed β
-- Good naming is sufficient β
-
-Decision: STOP HERE - Goals achieved, avoid bloat
-```
-
-## After Refactoring
-
-### Verify
-- [ ] Re-run `task lintwithfix` - Should pass
-- [ ] Run tests - Should still pass
-- [ ] Check coverage - Should maintain or improve
-- [ ] Code more readable? - Get feedback if unsure
-
-### May Need
-- **New types created** β Use @code-designing to validate design
-- **New functions added** β Ensure tests cover them
-- **Major restructuring** β Consider using @pre-commit-review
-
-## Output Format
-
-```
-π CONTEXT ANALYSIS
+CONTEXT ANALYSIS
Function: CreateUser (user/service.go:45)
Role: Core user creation orchestration
Called by:
- api/handler.go:89 (HTTP endpoint)
- cmd/user.go:34 (CLI command)
-- test/fixtures.go:123 (test fixtures)
Potential types spotted:
- Email: Complex validation logic scattered
- UserID: Generation and validation logic
-- UserCreationRequest: Multiple related fields
-π§ REFACTORING APPLIED
+REFACTORING APPLIED
-β
Patterns Successfully Applied:
+Patterns Successfully Applied:
1. Early Returns: Reduced nesting from 4 to 2 levels
2. Storifying: Extracted validate(), save(), notify()
3. Extract Type: Created Email and PhoneNumber types
-β Patterns Tried but Insufficient:
+Patterns Tried but Insufficient:
- Extract Function alone: Still too complex, needed types
-π― Types Created (with Juiciness Score):
+Types Created (with Juiciness Score):
-β
Email type (JUICY - Behavioral + Usage):
+Email type (JUICY - Behavioral + Usage):
- Behavioral: ParseEmail(), Domain(), LocalPart() methods
- Usage: Used in 5+ places across codebase
- Island: Testable in isolation
- β Invoke @testing skill to write tests
-β
PhoneNumber type (JUICY - Behavioral):
-- Behavioral: Parse(), Format(), CountryCode() methods
-- Validation: Complex international format rules
-- Island: Testable in isolation
-- β Invoke @testing skill to write tests
-
-β Types Considered but Rejected (NOT JUICY):
+Types Considered but Rejected (NOT JUICY):
- UserID: Only empty check, good naming sufficient
- Status: Just string constants, enum adequate
-ποΈ ARCHITECTURAL REFACTORING (if applicable)
-
-Trigger: noglobals linter failure
-
-Global Dependencies Identified:
-- env.Configs.NATsAddress: Used in 12 places
-- env.Configs.DBHost: Used in 8 places
-
-Dependency Rejection Applied:
-β
Level 1 (Bottom): Created NATSClient with injected address
-β
Level 2 (Middle): Created OrderService using clean types
-β¬οΈ Pushed env.Configs to: main() and HTTP handlers (2 locations)
-
-Islands of Clean Code Created:
-- messaging/nats_client.go: Ready for testing (isolated, injected deps)
-- order/service.go: Ready for testing (isolated, injected deps)
-β Invoke @testing skill to write tests for these islands
-
-Progress:
-- Before: 20 global accesses scattered throughout
-- After: 2 global accesses (entry points only)
-- Islands created: 2 new testable types
-
-π METRICS
+METRICS
Complexity Reduction:
-- Cyclomatic: 18 β 7 β
-- Cognitive: 25 β 8 β
-- LOC: 120 β 45 β
-- Nesting: 4 β 2 β
+- Cyclomatic: 18 β 7
+- Cognitive: 25 β 8
+- LOC: 120 β 45
+- Nesting: 4 β 2
-π FILES MODIFIED
+FILES MODIFIED
Modified:
- user/service.go (+15, -75 lines)
-- user/handler.go (+5, -20 lines)
Created (Islands of Clean Code):
- user/email.go (new, +45 lines) β Ready for @testing skill
-- user/phone_number.go (new, +38 lines) β Ready for @testing skill
-
-Next: Invoke @testing skill to write tests for new islands
-β
AUTOMATION COMPLETE
+AUTOMATION COMPLETE
Stopping Criteria Met:
-β
Linter passes (0 issues)
-β
All functions < 50 LOC
-β
Max nesting = 2 levels
-β
Code reads like a story
-β
No more juicy abstractions
+- Linter passes (0 issues)
+- All functions < 50 LOC
+- Max nesting = 2 levels
+- Code reads like a story
+- No more juicy abstractions
Ready for: @pre-commit-review phase
```
+
-## Learning from Examples
-
-For real-world refactoring case studies that show the complete thought process:
-
-**[Example 1: Storifying Mixed Abstractions](./examples.md#example-1-storifying-mixed-abstractions-and-extracting-logic-into-leaf-types)**
-- Transforms a 48-line fat function into lean orchestration + isolated type
-- Shows how to extract `IPConfig` type for collection and validation logic
-- Demonstrates creating testable islands of clean code
-
-**[Example 2: Primitive Obsession with Multiple Types](./examples.md#example-2-primitive-obsession-with-multiple-types-and-storifying-switch-statements)**
-- Transforms a 60-line function into a 7-line story by extracting 4 isolated types
-- Shows the Type Alias Pattern for config-friendly types
-- Demonstrates eliminating switch statement duplication
-- Fixed misleading function name (`validateCIDR` β `alignCIDRArgs`)
-
-**[Example 3: Dependency Rejection Pattern](./examples.md#example-3-dependency-rejection-pattern)**
-- Incremental elimination of global config access (`env.Configs.NATsAddress`)
-- Shows bottom-up approach: create clean islands one level at a time
-- Demonstrates testability benefits of dependency injection
-- Pragmatic stopping point: globals only at entry points
-
-See [examples.md](./examples.md) for complete case studies with thought process.
-
-## Integration with Other Skills
-
-### Invoked By (Automatic Triggering)
+
+**Invoked By (Automatic Triggering)**:
- **@linter-driven-development**: Automatically invokes when linter fails (Phase 3)
- **@pre-commit-review**: Automatically invokes when design issues detected (Phase 4)
-### Iterative Loop
-```
+**Iterative Loop**:
1. Linter fails β invoke @refactoring
2. Refactoring complete β re-run linter
3. Linter passes β invoke @pre-commit-review
4. Review finds design debt β invoke @refactoring again
-5. Refactoring complete β re-run linter
-6. Repeat until both linter AND review pass
-```
+5. Repeat until both linter AND review pass
-### Invokes (When Needed)
+**Invokes (When Needed)**:
- **@code-designing**: When refactoring creates new types, validate design
- **@testing**: Automatically invoked to write tests for new types/functions
- **@pre-commit-review**: Validates design quality after linting passes
See [reference.md](./reference.md) for complete refactoring patterns and decision tree.
+
+
+
+Refactoring is complete when ALL of the following are true:
+
+- [ ] Linter passes (0 issues)
+- [ ] All functions < 50 LOC
+- [ ] Max nesting β€ 2 levels
+- [ ] Code reads like a story (single abstraction level per function)
+- [ ] No more "juicy" abstractions to extract
+- [ ] Tests written for new types/functions (via @testing skill)
+- [ ] Ready for @pre-commit-review phase
+
diff --git a/go-linter-driven-development/skills/testing/SKILL.md b/go-linter-driven-development/skills/testing/SKILL.md
index ad53897..c7339e6 100644
--- a/go-linter-driven-development/skills/testing/SKILL.md
+++ b/go-linter-driven-development/skills/testing/SKILL.md
@@ -1,33 +1,49 @@
---
name: testing
-description: Automatically invoked to write tests for new types, or use as testing expert advisor for guidance and recommendations. Covers unit, integration, and system tests with emphasis on in-memory dependencies. Use when creating leaf types, after refactoring, during implementation, or when testing advice is needed. Ensures 100% coverage on leaf types with public API testing.
+description: |
+ Use when creating leaf types, after refactoring, during implementation, or when testing advice is needed.
+ Automatically invoked to write tests for new types, or use as testing expert advisor.
+ Covers unit, integration, and system tests with emphasis on in-memory dependencies.
+ Ensures 100% coverage on leaf types with public API testing.
---
-# Testing Principles
-
+
Principles and patterns for writing effective Go tests.
+Writes tests autonomously based on code structure and type design, and serves as testing expert advisor.
+
+**Reference**: See `reference.md` for comprehensive testutils patterns and DSL examples.
+
-## When to Use
+
+1. **Identify test level** needed (unit/integration/system)
+2. **Choose structure**: table-driven (simple) or testify suites (complex setup)
+3. **Write in pkg_test package** - test public API only
+4. **Use in-memory implementations** from testutils
+5. **Avoid pitfalls**: No time.Sleep, no conditionals in test cases
-### Automatic Invocation (Proactive)
+Ready after tests? Run linter: `task lintwithfix`
+
+
+
+
- **Automatically invoked** by @linter-driven-development during Phase 2 (Implementation)
- **Automatically invoked** by @refactoring when new isolated types are created
- **Automatically invoked** by @code-designing after designing new types
- **After creating new leaf types** - Types that should have 100% unit test coverage
- **After extracting functions** during refactoring that create testable units
+
-### Manual Invocation
+
- User explicitly requests tests to be written
- User asks for testing advice, recommendations, or "what to do"
- When testing strategy is unclear (table-driven vs testify suites)
- When choosing between dependency levels (in-memory vs binary vs test-containers)
- When adding tests to existing untested code
- When user needs testing expert guidance or consultation
+
+
-**IMPORTANT**: This skill writes tests autonomously based on the code structure and type design, and also serves as a testing expert advisor
-
-## Testing Philosophy
-
+
**Test only the public API**
- Use `pkg_test` package name
- Test types through their constructors
@@ -43,51 +59,55 @@ Principles and patterns for writing effective Go tests.
- Leaf types: 100% unit test coverage
- Orchestrating types: Integration tests
- Critical workflows: System tests
+
-## Test Pyramid
-
+
Three levels of testing, each serving a specific purpose:
-**Unit Tests** (Base of pyramid - most tests here)
+
- Test leaf types in isolation
- Fast, focused, no external dependencies
- 100% coverage target for leaf types
- Use `pkg_test` package, test public API only
+
-**Integration Tests** (Middle - fewer than unit)
+
- Test seams between components
- Test workflows across package boundaries
- Use real or in-memory implementations
- Verify components work together correctly
+
-**System Tests** (Top - fewest tests)
+
- Black box testing from `tests/` folder
- Test entire system via CLI/API
- Test critical end-to-end workflows
-- **Strive for independence in Go** (minimize external deps)
-
-## Reusable Test Infrastructure
+- **Dependency options**: in-memory mocks, binaries (exec.Command), or test-containers
+- Prefer in-memory when possible, but use appropriate level for the test
+
+
+
Build shared test infrastructure in `internal/testutils/`:
- In-memory mock servers with DSL (HTTP, DB, file system)
- Reusable across all test levels
- Test the infrastructure itself!
- Can expose as CLI tools for manual testing
-**Dependency Priority** (minimize external dependencies):
-1. **In-memory** (preferred): Pure Go, httptest, in-memory DB
-2. **Binary**: Standalone executable via exec.Command
-3. **Test-containers**: Programmatic Docker from Go
-4. **Docker-compose**: Last resort, manual testing only
+**Dependency Priority** (choose appropriate level):
+1. **In-memory** (fastest): Pure Go, httptest, in-memory DB - use when testing your code's logic
+2. **Binary** (isolated): Standalone executable via exec.Command - use when testing against real service
+3. **Test-containers** (realistic): Programmatic Docker from Go - use when you need real external services
+4. **Docker-compose** (full stack): For complex multi-service scenarios
-Goal: System tests should be **independent in Go** when possible.
+Choose based on what you're testing, not dogmatically. In-memory is fastest but sometimes you need real services.
See reference.md for comprehensive testutils patterns and DSL examples.
+
-## Workflow
-
-### Unit Tests Workflow
+
+
**Purpose**: Test leaf types in isolation, 100% coverage target
1. **Identify leaf types** - Self-contained types with logic
@@ -102,9 +122,9 @@ See reference.md for comprehensive testutils patterns and DSL examples.
- Always use named struct fields (linter reorders fields)
See reference.md for detailed patterns and examples.
+
-### Integration Tests Workflow
-
+
**Purpose**: Test seams between components, verify they work together
1. **Identify integration points** - Where packages/components interact
@@ -123,20 +143,22 @@ package user_test
```
See reference.md for integration test patterns with dependencies.
+
-### System Tests Workflow
-
+
**Purpose**: Black box test entire system, critical end-to-end workflows
1. **Place in tests/ folder** - At project root, separate from packages
2. **Test via CLI/API** - exec.Command for CLI, HTTP client for APIs
-3. **Minimize external deps** - Prefer: in-memory mocks > binary > test-containers
-4. **Strive for Go independence** - Pure Go tests, no Docker when possible
-5. **Test critical workflows** - User journeys, not every edge case
+3. **Choose dependency level** based on what you're testing:
+ - **In-memory**: Fastest, use when testing your code's behavior
+ - **Binary**: exec.Command to run real executables in separate process
+ - **Test-containers**: When you need real external services (DB, message queue)
+4. **Test critical workflows** - User journeys, not every edge case
-**Example structure:**
+**Example with in-memory mock:**
```go
-// tests/cli_test.go
+// tests/cli_test.go - Testing CLI against mock API
func TestCLI_UserWorkflow(t *testing.T) {
mockAPI := testutils.NewMockServer().
OnGET("/users/1").RespondJSON(200, user).
@@ -150,14 +172,84 @@ func TestCLI_UserWorkflow(t *testing.T) {
}
```
-See reference.md for comprehensive system test patterns.
+**Example with binary executable:**
+```go
+// tests/integration_test.go - Testing against real service binary
+func TestSystem_WithRealService(t *testing.T) {
+ // Start service binary in background
+ svc := exec.Command("./myservice", "--port", "8080")
+ svc.Start()
+ defer svc.Process.Kill()
+
+ // Wait for service to be ready
+ waitForHealthy(t, "http://localhost:8080/health")
+
+ // Run tests against real service
+ resp, err := http.Get("http://localhost:8080/api/users")
+ // Assert on response
+}
+```
+
+See reference.md for comprehensive system test patterns including test-containers.
+
-## Key Test Patterns
+
-**Table-Driven Tests:**
-- Separate success and error test functions (complexity = 1)
+
+**Table-Driven Tests (Cyclomatic Complexity = 1):**
+- **NEVER use wantErr bool** - Splits test logic, adds conditionals
+- **Max complexity = 1 inside t.Run()** - No if/else, no switch, no conditionals
+- Separate success and error test functions (TestFoo_Success, TestFoo_Error)
- Always use named struct fields (linter reorders fields)
-- No wantErr bool pattern (adds conditionals)
+
+```go
+// BAD - wantErr adds conditional, complexity > 1
+tests := []struct {
+ input string
+ want string
+ wantErr bool // NEVER DO THIS
+}{...}
+for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got, err := Parse(tt.input)
+ if tt.wantErr { // <- Conditional! Complexity > 1
+ require.Error(t, err)
+ } else {
+ require.NoError(t, err)
+ require.Equal(t, tt.want, got)
+ }
+ })
+}
+
+// GOOD - Separate functions, complexity = 1
+func TestParse_Success(t *testing.T) {
+ tests := []struct {
+ name string
+ input string
+ want string
+ }{...}
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got, err := Parse(tt.input)
+ require.NoError(t, err) // No conditionals
+ require.Equal(t, tt.want, got)
+ })
+ }
+}
+
+func TestParse_Error(t *testing.T) {
+ tests := []struct {
+ name string
+ input string
+ }{...}
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ _, err := Parse(tt.input)
+ require.Error(t, err) // No conditionals
+ })
+ }
+}
+```
**Testify Suites:**
- Only for complex infrastructure (HTTP servers, DBs, OpenTelemetry)
@@ -170,59 +262,50 @@ See reference.md for comprehensive system test patterns.
- Use sync.WaitGroup for concurrent operations
See reference.md for complete patterns with code examples.
+
-## Output Format
-
+
After writing tests:
```
-β
TESTING COMPLETE
+TESTING COMPLETE
-π Unit Tests:
+Unit Tests:
- user/user_id_test.go: 100% (4 test cases)
- user/email_test.go: 100% (6 test cases)
- user/service_test.go: 100% (8 test cases)
-π Integration Tests:
+Integration Tests:
- user/integration_test.go: 3 workflows tested
- Dependencies: In-memory DB, httptest mock server
-π― System Tests:
-- tests/cli_test.go: 2 end-to-end workflows
-- tests/api_test.go: 1 full API workflow
-- Infrastructure: In-memory mocks (pure Go, no Docker)
+System Tests:
+- tests/cli_test.go: 2 end-to-end workflows (in-memory mocks)
+- tests/api_test.go: 1 full API workflow (binary executable)
+- tests/db_test.go: 1 database workflow (test-containers)
Test Infrastructure:
- internal/testutils/httpserver: In-memory mock API with DSL
- internal/testutils/mockdb: In-memory database mock
+- internal/testutils/containers: Test-container helpers
Test Execution:
-$ go test ./... # All tests
+$ go test ./... # All tests (in-memory only)
$ go test -tags=integration ./... # Include integration tests
-$ go test ./tests/... # System tests only
+$ go test ./tests/... # System tests (may need containers)
-β
All tests pass
-β
100% coverage on leaf types
-β
No external dependencies required
+All tests pass
+100% coverage on leaf types
Next Steps:
1. Run linter: task lintwithfix
2. If linter fails β use @refactoring skill
3. If linter passes β use @pre-commit-review skill
```
+
-## Key Principles
-
-See reference.md for:
-- Table-driven test patterns
-- Testify suite guidelines
-- Real implementations over mocks
-- Synchronization techniques
-- Coverage strategies
-
-## Testing Checklist
-
-### Unit Tests
+
+
- [ ] All unit tests in pkg_test package
- [ ] Testing public API only (no private methods)
- [ ] Table-driven tests use named struct fields
@@ -230,26 +313,45 @@ See reference.md for:
- [ ] Using in-memory implementations from testutils
- [ ] No time.Sleep (using channels/waitgroups)
- [ ] Leaf types have 100% coverage
+
-### Integration Tests
+
- [ ] Test seams between components
- [ ] Use in-memory or binary dependencies (avoid Docker)
- [ ] Build tags for optional execution (`//go:build integration`)
- [ ] Cover happy path and error scenarios across boundaries
- [ ] Real or testutils implementations (minimal mocking)
+
-### System Tests
+
- [ ] Located in tests/ folder at project root
- [ ] Black box testing via CLI/API
-- [ ] Uses in-memory testutils mocks (pure Go)
-- [ ] No external dependencies (no Docker required)
+- [ ] Appropriate dependency level chosen (in-memory, binary, or test-containers)
- [ ] Tests critical end-to-end workflows
-- [ ] Fast execution, runs in CI without setup
+- [ ] Dependencies documented (what's needed to run tests)
+- [ ] CI-compatible (either fast in-memory or containerized setup)
+
-### Test Infrastructure
+
- [ ] Reusable mocks in internal/testutils/
- [ ] Test infrastructure has its own tests
- [ ] DSL provides readable test setup
- [ ] Can be exposed as CLI for manual testing
+
See reference.md for complete testing guidelines and examples.
+
+
+
+Testing is complete when ALL of the following are true:
+
+- [ ] All unit tests in pkg_test package testing public API only
+- [ ] Table-driven tests use named struct fields
+- [ ] No wantErr bool - success and error cases in separate test functions
+- [ ] Cyclomatic complexity = 1 inside t.Run() (no if/else, no switch)
+- [ ] Leaf types have 100% coverage
+- [ ] Integration tests cover component seams
+- [ ] System tests in tests/ folder with appropriate dependency level
+- [ ] No time.Sleep (using channels/waitgroups)
+- [ ] Tests pass and linter approves
+