Dotnet Writing Plans

⚠️ Spelling: It's saurun: (with U), not "sauron"

.NET Writing Plans

Overview

Plans are architectural blueprints, not copy-paste code. Each task references contracts defined in the architecture doc. Implementers use TDD skills to fill in the actual code.

Announce at start: "I'm using the dotnet-writing-plans skill to create the implementation plan."

Save plans to: _docs/plans/YYYY-MM-DD-<feature-name>.md

When NOT to Use

• Single-file bug fix with obvious cause and fix
• Config/environment changes (appsettings, launchSettings, .csproj tweaks)
• Renaming or moving files without logic changes
• Adding a NuGet package with no code changes beyond the import

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Claude:** **REQUIRED SUB-SKILL:** Use `saurun:dotnet-tdd` to implement this plan task-by-task with TDD.

**Goal:** [One sentence describing what this builds]

**Architecture:** `_docs/specs/{DATE}-{feature}-architecture.md`

**Tech Stack:** .NET 9, ASP.NET Core, EF Core 9, SQLite, xUnit, NSubstitute

---

Task Structure

### Task N: [Name]

**Implements:** [Contract reference from Architecture doc, e.g., "POST /lists/{id}/items (Architecture §API Contract)"]

**Files:**
- Create: `exact/path/to/File.cs`
- Test: `tests/exact/path/to/FileTests.cs`

**Behaviors:**
- [Happy path behavior]
- [Error case 1]
- [Error case 2]

**Dependencies:** Task X (if applicable)

Backend Task Examples

Domain Entity Task

### Task 2: ShoppingList aggregate

**Implements:** ShoppingList entity (Architecture §Entity Model)

**Files:**
- Create: `Domain/Aggregates/ShoppingList.cs`
- Test: `Tests/Domain/ShoppingListTests.cs`

**Behaviors:**
- Creating with valid name initializes empty items collection
- Adding item with valid name increases item count
- Adding item when at max capacity throws DomainException
- Removing non-existent item throws DomainException

API Endpoint Task

### Task 5: AddItem endpoint

**Implements:** POST /lists/{id}/items (Architecture §API Contract)

**Files:**
- Create: `Api/Endpoints/ShoppingListEndpoints.cs`
- Test: `Tests/Api/ShoppingListEndpointsTests.cs`

**Behaviors:**
- Valid input → 201 with ShoppingItemDto
- Validates per Architecture §API Contract

**Dependencies:** Task 2 (ShoppingList entity), Task 4 (DbContext)

Note: 401/404 for auth/invalid-id are omitted — standard patterns assumed. Validation rules reference architecture, not repeated.

Infrastructure Task

### Task 4: EF Core DbContext and migrations

**Implements:** Data persistence (Architecture §Infrastructure Decisions)

**Files:**
- Create: `Infrastructure/AppDbContext.cs`
- Create: `Infrastructure/Configurations/ShoppingListConfiguration.cs`
- Modify: `Program.cs` (add DbContext registration)

**Behaviors:**
- DbContext configured with SQLite provider
- ShoppingList entity mapped with owned Items collection
- Migration creates tables matching entity model

**Dependencies:** Task 2 (ShoppingList entity)

What Plans Include

What Plans Do NOT Include

Token budget: Plans for autonomous agents, not humans. Every repeated pattern wastes tokens. If architecture defines it, reference it — don't repeat it.

Test Infrastructure Task

Task 1 of every plan MUST set up test infrastructure:

### Task 1: Test infrastructure setup

**Implements:** Shared test helpers (N/A - infrastructure)

**Files:**
- Create: `Tests/CustomWebApplicationFactory.cs`
- Create: `Tests/TestHelpers.cs`

**Behaviors:**
- CustomWebApplicationFactory configured with SQLite in-memory
- TestHelpers provides authenticated HttpClient creation
- IClassFixture pattern ready for integration tests

Common Mistakes

Completion

After saving the plan, report:

"Plan saved to _docs/plans/<filename>.md. Ready for execution."