linter-driven-development

What this skill does

<objective>
Meta orchestrator for Go implementation workflow: design → test → lint → refactor → review → commit.
Use for any commit: features, bug fixes, refactors.

**Reference**: See `reference.md` for agent prompt templates, example reports, and output formats.
</objective>

<essential_principles>
**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.

**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)
</essential_principles>

<skill_invocation>
**CRITICAL**: When this skill says "Invoke @skill-name" or routes to "@skill-name", you MUST use the **Skill tool** explicitly.

| Notation | Skill Tool Call |
|----------|-----------------|
| @code-designing | `Skill(go-linter-driven-development:code-designing)` |
| @testing | `Skill(go-linter-driven-development:testing)` |
| @refactoring | `Skill(go-linter-driven-development:refactoring)` |
| @documentation | `Skill(go-linter-driven-development:documentation)` |

**DO NOT** just reference the skill in your response - actually invoke it using the Skill tool.
**DO NOT** read the skill file directly - use the Skill tool to load and execute it.

Example: When Phase 1 says "Invoke @testing skill to WRITE tests", you must call:
```
Skill(go-linter-driven-development:testing)
```
</skill_invocation>

<quick_start>
**Immediate Action**: Run Pre-Flight Check, then execute phases sequentially until commit-ready.

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
</quick_start>

<workflow>

<pre_flight_check>
**ALWAYS RUN FIRST**

<step name="confirm_intent">
Look for keywords: "implement", "ready", "execute", "do", "start", "continue", "next", "build", "create", "step 1", "task 2", or explicit "@linter-driven-development", "@ldd", "ldd"
</step>

<step name="verify_go_project">
Check that `go.mod` exists in the project root or parent directories.
</step>

<step name="find_commands">
**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**: `go test`, `make test`, `task test`
- **Lint command**: `golangci-lint run --fix`, `make lint`, `task lintwithfix`
- **Fallbacks**: `go test ./...` and `golangci-lint run --fix`
</step>

<step name="identify_plan">
Scan conversation history (last 50 messages) for step-by-step plan and which step to implement.
</step>

<decision_tree>
<decision condition="All conditions met" action="Announce 'Engaging autopilot mode for [description]' → Phase 1" />
<decision condition="Unclear intent" action="Ask for confirmation" />
<decision condition="No plan found" action="Suggest creating plan first (offer @code-designing)" />
<decision condition="Not Go project" action="Explain limitation" />
</decision_tree>
</pre_flight_check>

<phase name="1" title="Implementation Foundation">
**Design Architecture** (if new types/functions needed):
- Invoke @code-designing skill
- Output: Type design plan with self-validating domain types

**Write Tests First** (MANDATORY):
- Invoke @testing skill to WRITE tests (not just guidance)
- Create test files for all new types/functions
- Write table-driven tests or testify suites
- Target: 100% coverage on new leaf types

**Implement Code**:
- Follow coding principles from coding_rules.md
- Keep functions <50 LOC, max 2 nesting levels
- Use self-validating types, prevent primitive obsession

**Test Verification** (before proceeding):
1. For each new type file created:
   - Verify corresponding `*_test.go` exists
   - Run: `go test -cover ./path/to/package`
   - Verify: coverage > 0% (tests actually exercise code)
2. For leaf types: warn if coverage < 80%

**GATE**: DO NOT proceed to Phase 2 until:
- [ ] Test files exist for all new types
- [ ] `go test -cover` shows > 0% coverage for new packages
- [ ] No "no test files" or "[no tests to run]" messages
</phase>

<phase name="2" title="Quality Analysis">
**Invoke quality-analyzer agent** for parallel quality analysis.
See `reference.md` → "Agent Prompt Templates" for full prompt.

The agent automatically:
- Executes tests, linter, and code review in parallel (40-50% faster)
- Identifies overlapping issues with root cause analysis
- Returns structured report with prioritized fixes

<routing>
<route status="TEST_FAILURE" action="Enter Test Focus Mode (fix tests, retry)" />
<route status="CLEAN_STATE" action="Skip to Phase 4 (Documentation)" />
<route status="ISSUES_FOUND" action="Continue to Phase 3 (Fix Loop)" />
<route status="TOOLS_UNAVAILABLE" action="Report error, ask user to install tools" />
</routing>

<test_focus_mode>
Loop until tests pass:
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.
</test_focus_mode>
</phase>

<phase name="3" title="Iterative Fix Loop">

<linter_skill_routing>
**Linter Error → Skill Routing Table**

Route linter failures to the correct skill based on error type:

| Linter Error | Route To | Pattern Priority |
|--------------|----------|------------------|
| `nestif` (deep nesting) | @refactoring | 1. Storify, 2. Early returns, 3. Extract function |
| `argument-limit` (>4 params) | @code-designing | Create options struct type |
| `function-result-limit` (>3 returns) | @code-designing | Create result type |
| `confusing-results` | @code-designing | Create named result type |
| `cyclop`/`gocognit` (complexity) | @refactoring | 1. Storifying, 2. Extract type |
| `funlen` (function too long) | @refactoring | 1. Storify, 2. Extract function |
| `wrapcheck` (unwrapped error) | Direct fix | `fmt.Errorf("context: %w", err)` |
| `varnamelen` (short var name) | Direct fix | Rename variable to be descriptive |
| `early-return` (revive) | @refactoring | Apply early return pattern |
| `file-length-limit` (revive) | Analyze first → route | See file-level concerns below |
| **`package-size` hook RED (≥13 `.go` files)** | **@refactoring** | **`<package_decomposition>` 3-step design review — BLOCKING, decompose before next file** |
| **`package-size` hook YELLOW (8–12 `.go` files)** | **@refactoring** | **`<package_decomposition>` 3-step design review — *before* adding the next `.go` file to that package** |

**Package-size is a first-class linter failure.** The PostToolUse hook (`hooks/check-package-sizes.sh`) fires after every `Write`/`Edit`/`MultiEdit` and surfaces violations directly to Claude. Treat its output exactly like any other linter row above:
- ⛔ RED banner → exit 2 from the hook → blocking; route to `@refactoring` and complete `<package_decomposition>` *before* any other fix or feature step lands. Insert decomposition tasks at the front of the active todo list.
- ⚠️ YELLOW banner → non-blocking; if the *next* planned step adds a `.go` file to the named package, do `<package_decomposition>` first instead of writing the file. Skip otherwise.

Decomposition lands in its own commit (often its own PR). Do not mix package moves with feature changes.

**File-Level Concerns** (`file-length-limit` triggers at >450 lines):
When files exceed the limit, analyze structure first:

| File Pattern | Route To | Pattern |
|--------------|----------|---------|
| Multiple juicy types in one file | @code-designing | **Ju