Software-Engineering | Roy Gabriel

LLM Development Guide

Mon, 16 Feb 2026 12:00:00 -0500

This series turns LLM assistance into something you can run repeatedly without losing context.

You will be able to:

Turn vague work into explicit plans with verification and stop rules.
Write prompt documents that survive across sessions and handoffs.
Run large projects with phase documents and phase implementation prompt sets.
Preserve state with work notes so you can resume deterministically.
Execute in small units with review discipline and commit discipline.

Last updated: 2026-02-16

Questions? Contact me via my site contact form.

Found an issue? Open a GitHub issue.

Chapter 16: Worked Example: Converting an Ansible Playbook to a Go Temporal Workflow

Fri, 13 Feb 2026 09:00:00 -0500

Series: LLM Development Guide

Chapter 16 of 16

Previous: Chapter 15: Worked Example: Creating a Helm Chart From a Reference Chart

What you’ll be able to do

You’ll be able to migrate a procedural automation (for example, an Ansible playbook) into a durable Temporal workflow:

Extract discrete steps from the playbook.
Map steps to activities.
Implement a workflow that follows your team’s existing Temporal patterns.
Add verification and tests so the migration is not faith-based.

TL;DR

Start from a working reference workflow in your repo.
Paste both the playbook and the reference into the planning prompt.
Define activities first, then the workflow.
Verify with Temporal workflow tests and any integration checks you can run safely.

Scenario
Reference inputs
Plan and phase structure
Implementation skeleton (Go)
Verification
Gotchas

Scenario

Example: convert a playbook that creates a Kubernetes namespace and resource quota into a Temporal workflow.

Why this is a good fit:

Work is step-based.
You want retries and observability.
You want an execution history.

Reference inputs

Paste these into your planning prompt:

The playbook file (or the relevant section): playbooks/create-namespace.yml.
A reference workflow file that represents your team’s patterns.
A reference activity implementation file (if you have one).

Suggested commands:

sed -n '1,200p' playbooks/create-namespace.yml

sed -n '1,200p' internal/workflows/provision_cluster.go

ls -la internal/activities || true

Plan and phase structure

A reasonable phase split:

Phase 1: define activity I/O and implement activities.
Phase 2: implement workflow with retries and timeouts.
Phase 3: add tests.
Phase 4: register and deploy.

The plan should include verification per phase.

Implementation skeleton (Go)

This is a minimal skeleton to illustrate structure. It is intentionally not a full program.

package workflows

import (
 "time"

 "go.temporal.io/sdk/temporal"
 "go.temporal.io/sdk/workflow"
)

type CreateNamespaceInput struct {
 Namespace string
 CPULimit string
 MemLimit string
}

type CreateNamespaceOutput struct {
 Namespace string
}

// CreateNamespaceWorkflow orchestrates namespace creation.
// It assumes there are activities registered for create + quota + verify.
func CreateNamespaceWorkflow(ctx workflow.Context, input CreateNamespaceInput) (*CreateNamespaceOutput, error) {
 logger := workflow.GetLogger(ctx)
 logger.Info("starting namespace workflow", "namespace", input.Namespace)

 ctx = workflow.WithActivityOptions(ctx, workflow.ActivityOptions{
 StartToCloseTimeout: 10 * time.Minute,
 RetryPolicy: &temporal.RetryPolicy{
 MaximumAttempts: 3,
 },
 })

 // Pseudocode: adapt to your activity names and input/output types.
 // var nsResult activities.CreateNamespaceOutput
 // err := workflow.ExecuteActivity(ctx, activities.CreateNamespace, activities.CreateNamespaceInput{...}).Get(ctx, &nsResult)
 // if err != nil { return nil, err }

 // var quotaResult activities.CreateResourceQuotaOutput
 // err = workflow.ExecuteActivity(ctx, activities.CreateResourceQuota, activities.CreateResourceQuotaInput{...}).Get(ctx, &quotaResult)
 // if err != nil { return nil, err }

 // var verifyResult activities.VerifyNamespaceOutput
 // err = workflow.ExecuteActivity(ctx, activities.VerifyNamespace, activities.VerifyNamespaceInput{...}).Get(ctx, &verifyResult)
 // if err != nil { return nil, err }

 return &CreateNamespaceOutput{Namespace: input.Namespace}, nil
}

Notes:

The workflow.ExecuteActivity calls are left as pseudocode because activity package names and types are repo-specific.
Keep the skeleton syntactically correct.
Use your reference workflow as the style guide.

Verification

Your verification should include at least one of these:

Temporal workflow unit tests (Temporal test framework).
Activity unit tests (mock external systems).
A safe integration test against a non-production environment.

Example commands (adapt to your repo):

# Run unit tests.
go test ./...

# If you have a focused workflow test package.
go test ./internal/workflows -run TestCreateNamespaceWorkflow

Expected results:

Tests exit with code 0.
Failures are actionable (not timeouts with no logs).

Gotchas

If you skip the reference workflow, your new workflow will not match team patterns.
If you skip tests, you will not know whether retries and timeouts behave correctly.
LLMs will happily invent Temporal APIs. Verify imports and method names exist in your actual SDK version.

Chapter 15: Worked Example: Creating a Helm Chart From a Reference Chart

Wed, 11 Feb 2026 07:00:00 -0500

Series: LLM Development Guide

Chapter 15 of 16

Previous: Chapter 14: Building a Prompt Library: Governance + Quality Bar

Next: Chapter 16: Worked Example: Converting an Ansible Playbook to a Go Temporal Workflow

What you’ll be able to do

You’ll be able to create a production-quality Helm chart by following an existing chart in your repo as the reference:

Gather high-signal reference inputs.
Produce a phased plan and prompt docs.
Execute in reviewable commits.
Verify the chart renders and lints cleanly.

TL;DR

The reference chart is the source of truth for structure and conventions.
Paste the reference inputs into your planning prompt.
Execute one file at a time, with helm lint and helm template as gates.
If you do not have a real reference chart, pick a different worked example.

Scenario
Reference inputs
Phase 1: Plan
Phase 2: Prompt docs
Phase 3: Execute in logical units
Verification
Gotchas

Scenario

Goal: create a new chart (example: metrics-gateway) based on a known-good reference chart (example: event-processor).

This is a workflow example. You will need to substitute your real chart names and paths.

Reference inputs

Run these commands in your repo and paste the output into the planning prompt.

# Chart structure and key files.
tree charts/event-processor/

sed -n '1,200p' charts/event-processor/Chart.yaml

sed -n '1,200p' charts/event-processor/values.yaml

sed -n '1,200p' charts/event-processor/templates/_helpers.tpl

# If your reference chart uses these, include them too.
ls -la charts/event-processor | rg -n "values-" || true

Why this matters:

Structure: avoids “generic Helm” output.
Naming and labels: keeps your charts consistent.
Values shape: keeps operator UX consistent.

Phase 1: Plan

Create a plan that is mostly:

What files will exist.
What differences are specific to metrics-gateway (ports, probes, resources).
How you will verify each phase.

Example plan skeleton:

# metrics-gateway Helm Chart Plan

## Goals
- Create charts/metrics-gateway matching reference structure.
- Render successfully with helm template.
- Lint cleanly.

## References
- charts/event-processor/

## Phase 1: Analysis
- [ ] Document naming conventions from reference.

Verification:
- tree charts/event-processor

## Phase 2: Scaffold
- [ ] Create Chart.yaml
- [ ] Create values.yaml
- [ ] Create templates/_helpers.tpl

Verification:
- helm lint charts/metrics-gateway

## Phase 3: Core templates
- [ ] deployment
- [ ] service
- [ ] configmap

Verification:
- helm template charts/metrics-gateway > /tmp/rendered.yaml

## Definition of done
- [ ] helm lint exits 0
- [ ] helm template exits 0

Phase 2: Prompt docs

Generate one prompt file per phase. Include:

The plan path.
The work-notes path.
Reference chart file paths.
Deliverables (exact files).
Constraints (MUST and MUST NOT).
Verification commands.

A good constraint to include:

“Match reference structure exactly.” (and name what that means)

Phase 3: Execute in logical units

You have two implementation strategies.

Strategy A (recommended): copy the reference chart, then adapt

This is often the fastest way to guarantee structure consistency.

cp -R charts/event-processor charts/metrics-gateway

# Then rename strings and values in a controlled way.
# Review each replacement before committing.
rg -n "event-processor" charts/metrics-gateway

Now execute in logical units:

Update Chart.yaml.
Update values.yaml.
Update _helpers.tpl.
Update one template file at a time.

For each logical unit:

Update work notes.
Run helm lint.
Propose a commit.

Strategy B: scaffold from scratch, guided by the reference

Use this when copying would bring too much baggage.

You still paste the reference files, but ask the model to reproduce the structure explicitly.

Verification

Run both linting and rendering.

helm lint charts/metrics-gateway

helm template charts/metrics-gateway > /tmp/metrics-gateway.rendered.yaml

test -s /tmp/metrics-gateway.rendered.yaml

Expected results:

All commands exit with code 0.
The rendered YAML is non-empty.

Optional: diff against the reference chart structure:

# Compare structure only.
(cd charts/event-processor && find . -type f | sort) > /tmp/ref-files.txt
(cd charts/metrics-gateway && find . -type f | sort) > /tmp/new-files.txt

diff -u /tmp/ref-files.txt /tmp/new-files.txt || true

Expected result:

The file lists are close, with only intentional differences.

Gotchas

If you do not paste the reference files, you will get generic charts.
Be explicit about service ports, probe paths, and resource defaults.
Add negative constraints (“do not add ingress yet”) so scope doesn’t expand.

Continue -> Chapter 16: Worked Example: Converting an Ansible Playbook to a Go Temporal Workflow

Chapter 14: Building a Prompt Library: Governance + Quality Bar

Mon, 09 Feb 2026 06:00:00 -0500

Series: LLM Development Guide

Chapter 14 of 16

Previous: Chapter 13: Templates + Checklists: The Copy/Paste Kit

Next: Chapter 15: Worked Example: Creating a Helm Chart From a Reference Chart

What you’ll be able to do

You’ll be able to build a prompt library that doesn’t turn into a junk drawer:

Organize prompts by task type.
Define a consistent prompt entry format.
Set a contribution and maintenance policy.

TL;DR

A prompt library is a shared collection of prompts proven in real usage.
Require prereqs, recommended model tier, expected output, and common failure fixes.
Assign maintainers.
Version prompts with a changelog.

Library structure
Prompt entry template
Contribution guidelines
Governance
Verification

Library structure

A simple layout that scales:

prompt-library/
 README.md
 CONTRIBUTING.md
 planning/
 implementation/
 testing/
 review/
 debugging/

Keep it boring. Avoid inventing new categories every week.

Prompt entry template

Require a consistent format so prompts are reusable:

# <Task Name>

## When to use

## Prerequisites
-

## Recommended model tier

## The prompt

## Customization points

## Expected output

## Common issues and fixes

## Examples

## Changelog
- YYYY-MM-DD: <what changed>

Contribution guidelines

Set a quality bar:

A prompt must have been used successfully multiple times.
It must specify required reference files.
It must include verification.
It must include common failure modes and fixes.

A contribution checklist:

Used successfully 3+ times.
Another person can run it with the listed prereqs.
Changelog updated.

Governance

If nobody owns it, it rots.

Assign 1 to 2 maintainers to:

Review new prompts.
De-duplicate similar prompts.
Archive prompts that no longer work.
Run a quarterly cleanup.

Verification

Bootstrap the skeleton:

mkdir -p prompt-library/{planning,implementation,testing,review,debugging}

touch prompt-library/README.md

touch prompt-library/CONTRIBUTING.md

cat > prompt-library/planning/new-task.md <<'MD'
# New Task Planning

## When to use

## Prerequisites

## Recommended model tier

## The prompt

## Verification
MD

Expected result:

You have a real place to put prompts that worked, with enough structure to keep it maintainable.

Continue -> Chapter 15: Worked Example: Creating a Helm Chart From a Reference Chart

Chapter 13: Templates + Checklists: The Copy/Paste Kit

Sat, 07 Feb 2026 04:00:00 -0500

Series: LLM Development Guide

Chapter 13 of 16

Previous: Chapter 12: Team Collaboration: Handoffs, Shared Prompts, and Review

Next: Chapter 14: Building a Prompt Library: Governance + Quality Bar

What you’ll be able to do

You’ll be able to bootstrap the workflow in minutes:

Create plan/, prompts/, and work-notes/ with consistent templates.
Add a phase spec template for large, multi-phase projects.
Add a phase implementation prompt template for prompt-by-prompt execution.
Use session start and end checklists.
Generate PR descriptions that explain intent and verification.

TL;DR

Templates reduce prompt drift.
Keep them short and consistent.
Add verification to every phase.
For large projects, pair phase specs with implementation prompt docs.

Plan template
Prompt template
Phase spec template (large projects)
Phase implementation prompt template (large projects)
Work notes template
Session checklists
PR description template
Verification

Plan template

# <Project> Plan

## Overview

## Goals
-

## Context
- Reference implementation:
- Environment:

## Phases

## Definition of done
- [ ]

## Out of scope
-

## Risks / open questions
-

Prompt template

# Phase <X> - <Name>

## Role

## Context
- Plan:
- Work notes:
- References:

## Task

## Deliverables
1.

## Constraints
- MUST
- MUST NOT

## Session management
Update work notes with decisions, assumptions, open questions, and a session log entry.

## Verification
- Command:
- Expected:

## Commit discipline
Propose a commit message and wait for approval.

Phase spec template (large projects)

# Phase <N><Letter> - <Phase Name>

## Status
Planned

## Depends on
- <Phase dependency>

## Feature flag
- <flag name or n/a>

## Migration
- <none or required steps>

## Design rationale
<Why this phase exists and what risk it reduces>

## Tasks
### Prompt 1
- <task>

### Prompt 2
- <task>

## Files
### New
- <path>

### Modified
- <path>

### Referenced (read-only)
- <path>

## Exit criteria
- [ ] <build command> exits 0
- [ ] <vet/lint command> exits 0
- [ ] <test command> exits 0
- [ ] No ignored returned errors

## Progress notes

Phase implementation prompt template (large projects)

# Phase <N><Letter> - Implementation Prompts

Complete prompts sequentially. Do not continue when verification fails.

## Prompt 1 of <Total>: <Prompt Name>

Context files to load:
- <4 to 6 explicit paths>

Task:
- <exact implementation task>

Constraints:
- Stay within this prompt's scope.
- Handle all returned errors.
- Keep code small and reviewable.
- Do not proceed to the next prompt until verification passes.

Verification:
- <build command>
- <vet/lint command>
- <test command>

Commit discipline:
- Summarize what changed.
- Propose commit message.
- Wait for approval before moving on.

Work notes template

# Phase <X> - <Name>

## Status
- [ ] Not started
- [ ] In progress
- [ ] Blocked
- [ ] Complete

## Decisions

## Assumptions

## Open questions

## Session log

## Commits

Session checklists

Session start:

Identify the phase.
Load the phase prompt.
Load the current work notes.
Re-state the smallest goal for this session.

Session end:

Work notes updated.
Decisions logged with rationale.
Verification run.
Commits made (or clearly blocked).
Next step written down.

PR description template

## Summary

## Changes
-

## Out of scope
-

## Verification
-

## Review guide

## Follow-up
- [ ]

## References
- Work notes:
- Plan:

Verification

Create a local templates/ folder and seed the files:

mkdir -p templates

cat > templates/PLAN-template.md <<'MD'
# Project Plan

## Overview

## Goals

## Phases

## Definition of done
MD

cat > templates/PROMPT-template.md <<'MD'
# Phase - Prompt

## Role

## Context

## Task

## Constraints

## Verification

## Commit discipline
MD

cat > templates/WORK-NOTES-template.md <<'MD'
# Phase - Work Notes

## Status

## Decisions

## Session log
MD

Expected result:

You can start a new project by copying these templates and editing the placeholders.

Continue -> Chapter 14: Building a Prompt Library: Governance + Quality Bar

Chapter 12: Team Collaboration: Handoffs, Shared Prompts, and Review

Thu, 05 Feb 2026 02:00:00 -0500

Series: LLM Development Guide

Chapter 12 of 16

Previous: Chapter 11: Measuring Success: Solo + Team Metrics Without Fake Precision

Next: Chapter 13: Templates + Checklists: The Copy/Paste Kit

What you’ll be able to do

You’ll be able to run this workflow on a team without turning it into process theater:

Hand off work mid-phase without a meeting.
Share prompts that actually work.
Review LLM-assisted code with the same rigor as human code.

TL;DR

Teams fail at LLM work because chat context is not shareable.
Plans, prompt docs, and work notes make context portable.
Keep review focused on code and verification, not on how the code was produced.
Maintain a small set of “golden” reference implementations.

Handoff patterns
Shared prompt libraries
Review checklist
Verification

Handoff patterns

Mid-phase handoff

If you hand off in the middle of a phase, provide:

Updated work notes with status, decisions, open questions, and exact next step.
The phase prompt doc.
The reference implementation paths used.
Any verification output (test results, lint output).

Handoff template:

## Handoff: <Phase>

### Status
<What's done, what's in progress, what's blocked>

### Files to review
- <file 1>
- <file 2>

### Key decisions
- <Decision>: <Rationale>

### Open questions
- [ ] <Question>

### Immediate next step
<Exact command or file edit to do next>

### How to resume
1. Load prompts/<phase>.md
2. Load work-notes/<phase>.md
3. Continue from the last session log entry

Phase boundary handoff

Phase boundary handoffs are easier:

Work notes are marked complete.
The next phase starts cleanly.

Shared prompt libraries

A shared library reduces rework and increases consistency.

A reasonable structure:

prompt-library/
 planning/
 implementation/
 testing/
 review/

Quality bar:

Prompts are specific enough to be useful.
Prompts are general enough to be reused.
Prompts record “when to use” and “prereqs”.
Prompts have been used successfully multiple times.

Review checklist

LLM-assisted work should be reviewed like any other work.

High-signal checks:

Imports and APIs exist (no hallucinations).
Error handling is complete.
Output matches reference patterns.
Verification was actually run.
Commits are atomic and explain intent.
Tests test behavior, not just existence.

Verification

Create a shared template file so handoffs are consistent:

mkdir -p docs

cat > docs/llm-handoff-template.md <<'MD'
# LLM Work Handoff Template

## Phase

## Status

## Files to review

## Key decisions

## Open questions

## Verification run
- <command>
- Expected: <...>

## Next step

## How to resume
- Prompt:
- Work notes:
- References:
MD

Expected result:

Anyone can hand off work in under five minutes.

Continue -> Chapter 13: Templates + Checklists: The Copy/Paste Kit

Chapter 11: Measuring Success: Solo + Team Metrics Without Fake Precision

Tue, 03 Feb 2026 00:00:00 -0500

Series: LLM Development Guide

Chapter 11 of 16

Previous: Chapter 10: Stop Rules + Pitfalls: When to Upgrade, Bail, or Go Manual

Next: Chapter 12: Team Collaboration: Handoffs, Shared Prompts, and Review

What you’ll be able to do

You’ll be able to tell, with reasonable honesty, whether the workflow is helping:

Pick a small set of metrics you can actually measure.
Separate leading indicators (process) from lagging indicators (outcomes).
Avoid fake precision and vanity metrics.

TL;DR

If you can’t measure reliably, don’t invent numbers.
Track a baseline (a few representative tasks) before you claim improvement.
Favor cheap metrics: time to first commit, PR revision rounds, post-merge bugs.
Use leading indicators daily; use lagging indicators in retros.

What to measure
Solo baseline
Leading vs lagging indicators
Lightweight reporting template
Verification

What to measure

Pick a small set that maps to real outcomes.

Velocity indicators:

Time to first commit.
Phase completion time.
PR cycle time.

Quality indicators:

PR revision rounds.
Bugs caught in review.
Post-merge bugs.

Efficiency indicators:

Rework rate (time fixing output vs total time).
Session count per task.
Handoff success (can someone else continue without re-explaining).

Solo baseline

If you’re working solo, you can still create a baseline.

Track per task:

Start time.
First commit time.
Total time to done.
Number of “LLM retries” (how many prompt iterations for the same logical unit).
Bugs you found after “done”.

The point is not perfect measurement. The point is noticing patterns.

Leading vs lagging indicators

Leading indicators predict success:

Work notes are updated.
Prompts contain verification.
Commits are atomic.
References are provided.

Lagging indicators confirm success:

PR merged with low rework.
Low post-merge bug rate.
Handoffs succeed.

Lightweight reporting template

## LLM-Assisted Development Summary (Month)

### Adoption
- Tasks completed with workflow: <N>

### Velocity
- Median time to first commit: <X>
- Median PR cycle time: <Y>

### Quality
- Median PR revision rounds: <Z>
- Post-merge bugs: <N>

### Costs
- LLM cost estimate: <X>

### Notes
- What worked:
- What failed:
- Changes for next month:

Verification

Keep a simple CSV so you can graph later if you want.

mkdir -p work-notes

cat > work-notes/metrics.csv <<'CSV'
date,task,time_to_first_commit_minutes,total_time_minutes,llm_retries,pr_revision_rounds,post_merge_bugs,notes
CSV

Expected result:

You can append one row per task in under a minute.

Continue -> Chapter 12: Team Collaboration: Handoffs, Shared Prompts, and Review

Chapter 10: Stop Rules + Pitfalls: When to Upgrade, Bail, or Go Manual

Sat, 31 Jan 2026 23:00:00 -0500

Series: LLM Development Guide

Chapter 10 of 16

Previous: Chapter 9: Security & Sensitive Data: Sanitize, Don’t Paste Secrets

Next: Chapter 11: Measuring Success: Solo + Team Metrics Without Fake Precision

What you’ll be able to do

You’ll be able to avoid the two common failure outcomes:

Spending hours fighting the model.
Shipping output you can’t review.

You’ll do it with explicit stop rules, upgrade triggers, and a short recovery checklist.

TL;DR

If the change is under a minute manually, do it manually.
If you can’t review the output competently, don’t ship it.
If you’re on your third attempt for the same logical unit, upgrade or re-scope.
Add verification steps to plans and prompts so “done” is testable.

Stop rules
Top pitfalls
Recovery checklist
Verification

Stop rules

These are pragmatic defaults. Tune them to your environment.

Stop rule 1: tiny changes

If it is a tiny change (one line, one rename, one version bump), do it manually.

LLM overhead is real:

You still have to explain.
You still have to review.
You still have to verify.

Stop rule 2: you can’t review it

Never commit code you could not explain in a review.

If you don’t understand the domain:

break the work into smaller pieces you can understand, or
involve a reviewer who does.

Stop rule 3: you’re fighting output quality

The 10-minute rule:

If you’ve spent about 10 minutes fighting the output, stop.
Upgrade the model tier, or shrink the scope to a smaller logical unit.

Stop rule 4: high-risk code needs extra caution

Be cautious with:

Authentication and authorization.
Cryptography.
Payment flows.
Input validation.

You can still use LLMs, but the bar for review and verification is higher.

Top pitfalls

These show up repeatedly.

Trusting output without review.
Skipping planning.
Not providing reference implementations.
Letting sessions run too long.
Scope creep mid-session.
Vague prompts.
Not capturing decisions.
No verification step.

A simple rule:

If you wouldn’t merge a junior developer’s PR without review, don’t merge LLM output without review.

Recovery checklist

When things go wrong:

Stop iterating on bad output.
Decide what kind of problem it is:
- prompt problem,
- model capability problem,
- task is a poor fit.
Simplify:
- smaller logical unit,
- more references,
- clearer constraints.
Fresh session if context has drifted.
Manual fallback is a valid outcome.

Verification

Create a one-page stop-rules file so you can apply this consistently across tasks:

mkdir -p work-notes

cat > work-notes/stop-rules.md <<'MD'
# Stop Rules (Personal Defaults)

## Manual first
- If change is <= 1 minute manually, do it manually.

## Upgrade triggers
- Third attempt on same logical unit.
- Repeated misunderstandings.
- Output ignores constraints.

## Bail triggers
- I cannot review this competently.
- Task requires live debugging with runtime state.
- Sensitive data would be required to reproduce.

## Required gates
- Verification commands exist in plan.
- Verification commands exist in prompt.
- Work notes updated before continuing.
MD

Expected result:

You have a written policy you can apply without debating every time.

Continue -> Chapter 11: Measuring Success: Solo + Team Metrics Without Fake Precision

Chapter 9: Security & Sensitive Data: Sanitize, Don't Paste Secrets

Thu, 29 Jan 2026 21:00:00 -0500

Series: LLM Development Guide

Chapter 9 of 16

Previous: Chapter 8: Choosing the Right Model: Capability Tiers, Not Hype

Next: Chapter 10: Stop Rules + Pitfalls: When to Upgrade, Bail, or Go Manual

What you’ll be able to do

You’ll be able to use LLMs without doing something reckless:

Apply a concrete “never paste” list.
Sanitize code, config, and logs into safe examples.
Add a verification step so you don’t ship secrets.

TL;DR

Assume anything you paste could be logged or retained.
If you wouldn’t publish it publicly, don’t paste it.
Replace real values with placeholders.
Sanitize logs aggressively.
Verify your workspace for leaked secrets before you commit.

The core principle
Never paste list
Sanitization patterns
Verification
Failure modes

The core principle

Assume anything you send to an LLM could be stored.

Even with enterprise offerings, policies change. Check vendor policy as of 2026-02-14 (and your organization’s approved tools list) before using any tool with internal data.

Never paste list

Do not paste:

Credentials: API keys, tokens, passwords, private keys.
PII: customer names, emails, addresses, health data.
Production data: real records, full dumps, support tickets.
Security configs: firewall rules, IAM policies, internal IPs.
Proprietary secrets: unreleased product details, trade secrets.

Use the “Would I post this publicly?” test.

Sanitization patterns

Replace sensitive values with descriptive placeholders.

Go example:

// Before (do not paste)
// db, err := sql.Open("postgres", "host=prod-db.internal user=admin password=SuperSecret123 dbname=customers")

// After (safe to paste)
db, err := sql.Open("postgres", "host=DATABASE_HOST user=DATABASE_USER password=DATABASE_PASSWORD dbname=DATABASE_NAME")
if err != nil {
 return err
}

YAML example:

# Before (do not paste)
# data:
# api-key: YWN0dWFsLWFwaS1rZXktaGVyZQ==

# After (safe to paste)
data:
 api-key: <BASE64_ENCODED_API_KEY>
 webhook-secret: <BASE64_ENCODED_WEBHOOK_SECRET>

Logs:

Remove emails.
Replace internal hostnames.
Replace IPs with documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24).

Verification

Before you paste or commit, search your workspace for obvious secret patterns.

These commands are noisy, but useful:

# High-signal patterns.
rg -n "(AKIA[0-9A-Z]{16}|BEGIN (RSA|OPENSSH) PRIVATE KEY|xox[baprs]-|ghp_[A-Za-z0-9]{36})" . || true

# Common key/value names.
rg -n "(?i)(api[_-]?key|secret|token|password)\s*[:=]" . || true

# Emails (often indicates logs or real data got copied).
rg -n "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}" . || true

# Check staged changes specifically.
git diff --cached

Expected results:

No obvious credentials or private keys appear in diffs.
If matches exist, sanitize and regenerate the example.

Failure modes

Sharing real logs that contain tokens in URLs.
Copying a Kubernetes Secret verbatim.
Letting an IDE plugin send your whole file without noticing.
Assuming “enterprise” means “no risk” without verifying current policy.

Continue -> Chapter 10: Stop Rules + Pitfalls: When to Upgrade, Bail, or Go Manual

Chapter 8: Choosing the Right Model: Capability Tiers, Not Hype

Tue, 27 Jan 2026 19:00:00 -0500

Series: LLM Development Guide

Chapter 8 of 16

Previous: Chapter 7: Large Projects with Phase Documents + Implementation Prompts

Next: Chapter 9: Security & Sensitive Data: Sanitize, Don’t Paste Secrets

What you’ll be able to do

You’ll be able to pick a model and interface deliberately:

Use capability tiers instead of memorizing brand names.
Upgrade quickly when quality is the bottleneck.
Avoid wasting flagship models on structured boilerplate.

TL;DR

Treat model choice as a cost-of-mistakes problem.
Use flagship models for planning, debugging, and high-stakes decisions.
Use mid-tier models for implementation with strong references.
Use fast/cheap models for boilerplate and simple transformations.
If you’ve spent ~10 minutes fighting output quality, upgrade or shrink scope.

As-of note

As of 2026-02-14, model names, pricing, and product policies change frequently. Prefer tier-based guidance, and verify vendor policies directly before using tools with sensitive data.

The capability tiers
Task-to-tier mapping
Red flags: upgrade now
A selection checklist
Verification

The capability tiers

Think in tiers:

Flagship: best reasoning and instruction-following for novel work.
Mid-tier: strong general performance for structured work with references.
Fast/cheap: good for simple tasks, higher error rate on complex reasoning.

This framing stays useful even when names change.

Task-to-tier mapping

Use flagship for:

Planning and architecture.
Debugging complex failures.
Security-sensitive review.
Anything where mistakes are expensive.

Use mid-tier for:

Implementation that follows existing patterns.
Refactors with clear examples.
Writing tests when the behavior is already defined.

Use fast/cheap for:

Syntax lookups.
Boilerplate you will review.
Mechanical transformations.

Red flags: upgrade now

Upgrade when you see:

The model repeats the same misunderstanding.
Output ignores constraints.
“Looks right” code fails in tests.
You are on the third prompt iteration for the same unit.

The cheapest model is the one that gets you to a correct verified change with the least total time.

A selection checklist

Before you start, answer:

Is this novel or pattern-following?
Do I have reference implementations?
What is the cost of mistakes?
Is this structured or ambiguous?
Am I debugging or implementing?

If uncertain:

Start with flagship for planning.
Drop to mid-tier once you have a stable pattern and good references.

Verification

A practical way to keep this from being hand-wavy is to force a written decision per phase.

Create a small note file per task:

mkdir -p work-notes

cat > work-notes/model-selection.md <<'MD'
# Model Selection (Per Task)

## Task
<What are we doing?>

## Risk
- Cost of mistakes:
- Can I review the output competently?

## References
- <Paths to reference implementations>

## Model decision
- Tier: <flagship|mid-tier|fast>
- Why:
- When to upgrade:

## Outcome
- Did we upgrade?
- What broke / what worked:
MD

Expected result:

You can justify the model choice in one minute.
You have a trigger for upgrading when output quality is the bottleneck.

Continue -> Chapter 9: Security & Sensitive Data: Sanitize, Don’t Paste Secrets

Chapter 7: Large Projects with Phase Documents + Implementation Prompts

Mon, 26 Jan 2026 20:00:00 -0500

Series: LLM Development Guide

Chapter 7 of 16

Previous: Chapter 6: Scaling the Workflow: Phases, Parallelism, Hygiene

Next: Chapter 8: Choosing the Right Model: Capability Tiers, Not Hype

What you’ll be able to do

You’ll be able to run large, multi-phase delivery with less drift by introducing two explicit artifacts:

A phase specification document that defines scope, dependencies, files, and exit criteria.
A phase implementation prompt document that defines the prompt-by-prompt execution contract.
A repeatable operating cadence for execution, verification, and commits.

TL;DR

Large projects fail when a single prompt tries to carry the whole implementation plan.
Use one phase spec and one implementation-prompt file per sub-phase.
Execute prompts sequentially; do not continue if build/vet/test gates fail.
Keep context loading explicit for each prompt.
For copy/paste templates, use Chapter 13: Templates + Checklists: The Copy/Paste Kit .

Why this pattern exists
The two-document system
Worked example: a multi-phase engineering initiative
Execution protocol for prompt files
Verification
Failure modes

Why this pattern exists

For a one-day task, a plan plus one execution prompt is usually enough.

For multi-week work, that breaks down:

Context gets too large and detail gets dropped.
Sessions diverge when constraints are implied instead of written.
Verification becomes optional instead of required.
Commits become large and hard to review.

The fix is to treat phase docs and implementation prompt docs as first-class project artifacts.

The two-document system

For each sub-phase, create two files.

1) Phase spec document

Purpose: define what this sub-phase must accomplish and how completion is validated.

Typical sections:

Status, dependency, and migration notes.
Design rationale (why this slice exists now).
Tasks grouped by prompt number.
Files: new, modified, and referenced-only.
Exit criteria with concrete commands and expected results.
Progress notes placeholder.

2) Phase implementation prompt document

Purpose: define exactly how execution happens, prompt by prompt.

Each prompt should include:

Context files to load (small, explicit list).
Task details: signatures, interfaces, constraints.
Quality gates and required verification commands.
Stop condition: do not proceed until the current prompt passes.

A useful pattern is to couple one prompt to one logical implementation unit.

Worked example: a multi-phase engineering initiative

Assume you are delivering a new runtime capability over six weeks.

You split work into:

Phase A: contracts and types.
Phase B: core implementation.
Phase C: API and integration points.
Phase D: tests and validation.
Phase E: observability and rollout safety.

For Phase B, your phase spec might look like this:

# Phase B - Core Implementation

## Status
Planned

## Depends on
Phase A

## Design rationale
Phase B isolates core behavior behind the contracts from Phase A.
This prevents API and infrastructure concerns from polluting the core logic.

## Tasks
### Prompt 1
- Implement core orchestration types and constructor.

### Prompt 2
- Implement main execution method with deterministic error paths.

### Prompt 3
- Add unit tests for success and failure branches.

## Files
### New
- internal/core/runtime.go
- internal/core/runtime_test.go

### Modified
- internal/core/types.go

### Referenced (read-only)
- internal/contracts/interfaces.go

## Exit criteria
- [ ] `go build ./internal/core/...` exits 0
- [ ] `go vet ./internal/core/...` exits 0
- [ ] `go test ./internal/core/...` exits 0
- [ ] No unchecked returned errors

## Progress notes

Now pair it with a Phase B implementation prompt file:

# Phase B - Implementation Prompts

## Prompt 1 of 3: Runtime skeleton

Context files to load:
- docs/phases/PHASEB.md
- internal/contracts/interfaces.go
- internal/core/types.go
- README.md

Task:
- Create `internal/core/runtime.go` with constructor and public methods.

Constraints:
- Do not change files outside listed scope.
- Handle all returned errors explicitly.
- Keep methods short enough to remain reviewable.

Verification:
- `go build ./internal/core/...`
- `go vet ./internal/core/...`

Stop rule:
- Do not proceed to Prompt 2 until both commands pass.

This is intentionally boring. Boring is what scales.

Execution protocol for prompt files

Use the same cadence for every prompt in a sub-phase:

Load only listed context files.
Execute exactly one prompt.
Update work notes (decisions, assumptions, blockers, next step).
Run required verification gates.
Commit one logical unit.
Move to the next prompt.

Suggested commit discipline:

One commit per prompt when prompts are independent.
One commit per tightly coupled prompt pair when separation creates broken intermediate states.
Message format should state scope and intent clearly.

When prompt counts are high, add a completion table in work notes:

## Prompt progress
- [x] Prompt 1
- [x] Prompt 2
- [ ] Prompt 3
- [ ] Prompt 4

Verification

You can verify this system is functioning with mechanical checks.

# All phase specs have exit criteria.
rg -n "^## Exit criteria" docs/phases/PHASE*.md

# All prompt docs define context loading and verification.
rg -n "^Context files to load:|^Verification:" docs/phases/*-PROMPT.md

# Work notes track progression.
rg -n "^## Prompt progress|^## Session log" work-notes || true

Expected results:

Every phase spec has explicit exit criteria.
Every prompt file defines context and verification.
Session state is recoverable without re-explaining the whole project.

Failure modes

Phase docs describe architecture but skip executable gates.
Prompt docs are too broad (“implement phase”) and lose determinism.
Prompts proceed despite failing verification.
Context file lists are bloated and include unrelated material.

If this starts happening, shrink prompt scope and tighten exit criteria before continuing.

Continue -> Chapter 8: Choosing the Right Model: Capability Tiers, Not Hype

Chapter 6: Scaling the Workflow: Phases, Parallelism, Hygiene

Sun, 25 Jan 2026 18:00:00 -0500

Series: LLM Development Guide

Chapter 6 of 16

Previous: Chapter 5: The Execution Loop: Review Discipline + Commit Discipline

Next: Chapter 7: Large Projects with Phase Documents + Implementation Prompts

What you’ll be able to do

You’ll be able to take the same workflow and scale it up without chaos:

Split work into phases that do not overlap on files.
Run parallel sessions or agents safely.
Decide when artifacts stay local vs. get committed.

TL;DR

Scale by splitting phases, not by writing bigger prompts.
Keep phase files small (rule of thumb: under ~200 lines).
Parallel work requires clean boundaries and explicit interfaces.
Decide up front whether plan/, prompts/, work-notes/ live in git.

When to sub-phase
Parallel execution requirements
Repository hygiene
Verification
Gotchas

When to sub-phase

Sub-phase when:

A phase touches too many files.
The phase cannot be verified independently.
The phase depends on decisions that are not written down.

Example layout:

plan/
 phase-1a-analysis.md
 phase-1b-design.md
 phase-2a-scaffold.md
 phase-2b-core-impl.md
 phase-3-validation.md

Keep each phase “one session friendly”: small enough to complete (or at least checkpoint) in 1 to 2 sessions.

At this point, many teams benefit from formalizing each sub-phase with two files: a phase spec and a phase implementation prompt file. The next chapter walks through that pattern in detail.

Parallel execution requirements

Parallel work is possible, but only if you make boundaries explicit.

Requirements:

No overlapping files between parallel phases.
Explicit interfaces (types, APIs, data shapes) written down.
A merge plan (who rebases, who resolves conflicts, how often you sync).

A simple pattern:

Phase A defines interfaces and contracts.
Phase B implements with those interfaces.
Phase C adds tests and validation.

Repository hygiene

Decide whether artifacts are local scaffolding or part of the repo.

Common default:

Keep plan/, prompts/, work-notes/ local (gitignored).

Commit them deliberately when they become:

Long-lived docs.
Reusable templates.
Onboarding material.

If you commit them, consider moving to docs/ and editing for humans.

Verification

These checks help you catch “phases are too big” early:

# Find phase files that are getting too large.
# (This uses line count as a blunt proxy.)
find plan -type f -name '*.md' -maxdepth 2 -print0 | xargs -0 wc -l | sort -n

# Find prompts that do not reference work notes.
rg -n "work-notes/" prompts || true

# Find phases that might overlap on files (manual review).
# Start by listing deliverables per phase in each prompt doc.
rg -n "^## Deliverables" -n prompts

Gotchas

Parallelization without clean boundaries just creates merge conflicts faster.
If you don’t define interfaces early, later phases stall.
If artifacts are committed, treat them like code: review, version, maintain.

Continue -> Chapter 7: Large Projects with Phase Documents + Implementation Prompts

Chapter 5: The Execution Loop: Review Discipline + Commit Discipline

Fri, 23 Jan 2026 16:00:00 -0500

Series: LLM Development Guide

Chapter 5 of 16

Previous: Chapter 4: Work Notes: External Memory + Running Log

Next: Chapter 6: Scaling the Workflow: Phases, Parallelism, Hygiene

What you’ll be able to do

You’ll be able to run an LLM through implementation work in a way that stays reviewable:

One logical unit at a time.
Verification before claiming “done”.
Atomic commits with clear intent.
Notes updated as part of the loop.

TL;DR

Never skip: update notes, verify, propose commit, review.
A “logical unit” is the smallest change that is independently reviewable.
Treat LLM output like junior output: it needs review.
Keep commits small to make rollback cheap.

The execution loop
What counts as a logical unit
Commit discipline
Verification
Failure modes

The execution loop

This loop is intentionally repetitive:

Load prompt + work-notes
-> implement one logical unit
-> update work-notes
-> verify
-> propose commit
-> you review
-> commit
-> repeat

If you skip the middle steps, your “agent” becomes a vibes-based code generator.

What counts as a logical unit

A logical unit is a change that:

Has a clear purpose.
Can be verified.
Can be reviewed in isolation.
Does not leave the repo in a half-broken state.

Examples:

Add one Kubernetes template file.
Add one Go type + its tests.
Add one API endpoint handler.

Non-examples:

“Implement everything for phase 2”.
“Half a refactor”.
“Quick fixes”.

Commit discipline

Use a consistent commit format so you can scan history later.

Example commit message:

feat(helm): add service template for metrics-gateway

- Exposes port 9090 as ClusterIP
- Follows event-processor naming and labels
- No ingress in this commit

Refs: work-notes/phase-2b-core-resources.md

In prompts, require the model to:

Summarize what changed.
Explain why.
Propose a message.
Wait for approval.

Verification

Verification is context-specific, but the shape is consistent:

Build.
Test.
Lint.
Render config.

Generic verification commands you can adapt:

# Make sure you know what is staged and what is not.
git status --porcelain

git diff

# Run the repo's verification gates.
# Replace these with your actual commands.
go test ./...

# After the commit, ensure you're clean.
git status --porcelain

Expected results:

Before committing, git diff matches the logical unit scope.
After committing, git status --porcelain is empty.
Tests and other gates exit 0.

Failure modes

The model keeps “just one more change”-ing.
- Fix: put explicit stop points in the prompt.
You don’t verify.
- Fix: add verification commands to plan and prompt docs.
Commits include unrelated changes.
- Fix: shrink the logical unit and split the work.
You approve output you can’t review.
- Fix: stop and do it manually or bring in a reviewer.

Continue -> Chapter 6: Scaling the Workflow: Phases, Parallelism, Hygiene

Chapter 4: Work Notes: External Memory + Running Log

Wed, 21 Jan 2026 14:00:00 -0500

Series: LLM Development Guide

Chapter 4 of 16

Previous: Chapter 3: Prompt Documents: Prompts That Survive Sessions

Next: Chapter 5: The Execution Loop: Review Discipline + Commit Discipline

What you’ll be able to do

You’ll be able to keep multi-session work consistent by maintaining work notes that:

Preserve the model’s working state outside the chat.
Capture decisions and rationale for later review.
Make handoffs possible.
Provide a deterministic “resume” prompt.

TL;DR

LLMs have no durable memory. If it’s not written down, it doesn’t exist next session.
Mirror work-notes/ files to your phases exactly.
Track: status, decisions, assumptions, open questions, session log, commits.
In your prompts, require the model to update notes before moving forward.

Directory alignment
A work-notes template you can paste
Session start and session end prompts
Verification
Gotchas

Directory alignment

Keep your three directories aligned so you can load one phase without dragging unrelated context into the session:

plan/phase-2a-scaffolding.md
prompts/phase-2a-scaffolding.md
work-notes/phase-2a-scaffolding.md

This makes sessions resumable and makes parallel work possible.

A work-notes template you can paste

# Phase <X> - <Phase Name>

## Status
- [ ] Not started
- [ ] In progress
- [ ] Blocked
- [ ] Complete

## Decisions
- <Decision>: <Rationale>

## Assumptions
- <Assumption>

## Open questions
- [ ] <Question>

## Session log

### <YYYY-MM-DD HH:MM>
- What changed:
- Why:
- Blockers:
- Next:

## Commits
- <hash> - <message>

You can keep it simple. The win is consistency.

Session start and session end prompts

Start a session

Paste your phase prompt and current work notes, and tell the model to continue from the last session.

I'm continuing work on Phase <X>.

Prompt:
<paste prompts/phase-X.md>

Current state:
<paste work-notes/phase-X.md>

Please:
1. Summarize where we are (3 to 4 sentences).
2. List blockers and open questions.
3. Confirm the next logical unit.
4. Proceed with the next logical unit.

End a session

Before we stop:
1. Update the session log with what we did and what is next.
2. Ensure decisions, assumptions, and open questions are current.
3. Propose a commit message for any completed logical unit.
4. Show the updated work-notes file.

Verification

You can verify your notes are doing their job by forcing a cold start:

Start a new chat.
Paste only the phase prompt and the work-notes file.
See if you can resume without re-explaining anything.

Mechanical checks:

# Work notes exist and are non-empty.
find work-notes -type f -name '*.md' -maxdepth 2 -print -exec test -s {} \;

# Work notes have at least the core sections.
rg -n "^## (Status|Decisions|Assumptions|Open questions|Session log|Commits)" work-notes

Gotchas

Notes without rationale are not useful later.
If you let the model continue without updating notes, the next session will drift.
Avoid dumping raw logs with sensitive data. Sanitize first.

Continue -> Chapter 5: The Execution Loop: Review Discipline + Commit Discipline

Chapter 3: Prompt Documents: Prompts That Survive Sessions

Mon, 19 Jan 2026 12:00:00 -0500

Series: LLM Development Guide

Chapter 3 of 16

Previous: Chapter 2: Planning: Plan Artifacts, Constraints, Definition of Done

Next: Chapter 4: Work Notes: External Memory + Running Log

What you’ll be able to do

You’ll be able to create prompt documents that:

Encode intent precisely so you don’t re-explain yourself.
Align to plan phases so scope stays tight.
Include verification steps and explicit stop points.
Tell the model how to update work notes and propose commits.

TL;DR

A prompt doc is an artifact, not a chat message.
Use one prompt file per phase.
Always include: role, context, task, constraints, deliverables, verification, session management.
Put negative constraints in writing (“MUST NOT”).
Keep prompts copy/pasteable and path-specific.

Why prompt docs matter
Anatomy of a good prompt
A template you can copy
Verification
Failure modes

Why prompt docs matter

If you’re doing anything bigger than a one-off snippet, the prompt itself becomes part of the system.

Prompt docs:

Reduce “prompt drift” across sessions.
Make handoffs possible.
Create an audit trail of what was asked.
Force you to pin down deliverables and done-ness.

Anatomy of a good prompt

At minimum, include these sections:

Role: what expertise you’re invoking.
Context: plan path, work-notes path, reference implementation paths.
Task: what to do now.
Constraints: what must and must not happen.
Deliverables: exact files and outputs expected.
Verification: commands and expected results.
Session management: how to update work notes.
Commit discipline: atomic commits, propose messages, wait for approval.

If your prompt is missing verification and stop rules, you’re inviting “looks right” output.

A template you can copy

# Phase <X> - <Phase Name>

## Role
You are a senior software engineer.

## Context
- Plan: plan/<phase>.md
- Work notes: work-notes/<phase>.md
- Reference implementations:
 - <path 1>
 - <path 2>

## Task
Implement the next logical unit for this phase.

## Constraints (follow exactly)
- MUST follow patterns in the reference implementations.
- MUST keep changes scoped to this phase.
- MUST include tests when applicable.
- MUST propose verification commands.
- MUST NOT add new dependencies unless explicitly approved.

## Deliverables
1. <file path> - <what it contains>
2. <file path> - <what it contains>

## Session management
As you work:
- Update work-notes/<phase>.md:
 - Decisions (with rationale)
 - Assumptions
 - Open questions
 - Session log entry
- After each logical unit, pause and show the updated notes section.

## Verification
After implementing the logical unit, run or propose:
- <command>
- Expected: <exit 0 / output contains X>

## Commit discipline
After verification:
1. Summarize what changed and why.
2. Propose a conventional commit message.
3. Wait for approval before continuing.

Refs: work-notes/<phase>.md

Notes:

Use real paths.
Put constraints in a dedicated section.
Repeat the most important constraints near the end.

Verification

You can verify prompt docs are usable by checking two things:

You can paste the entire file verbatim into a new session.
A new session produces the same behavior because paths and constraints are explicit.

Concrete checks:

# Prompts exist and are non-empty.
find prompts -type f -name '*.md' -maxdepth 2 -print -exec test -s {} \;

# Prompts mention work-notes paths.
rg -n "work-notes/" prompts

Expected results:

Each prompt file is non-empty.
Each prompt references a work-notes file.

Failure modes

Prompts that say “use the config file” without a path.
Constraints buried in prose instead of a dedicated section.
Prompts that do not mention verification.
Prompts that do not tell the model to stop after a logical unit.

Continue -> Chapter 4: Work Notes: External Memory + Running Log

Chapter 2: Planning: Plan Artifacts, Constraints, Definition of Done

Sat, 17 Jan 2026 11:00:00 -0500

Series: LLM Development Guide

Chapter 2 of 16

Previous: Chapter 1: A Practical Workflow for LLM-Assisted Development That Doesn’t Collapse After Day 2

Next: Chapter 3: Prompt Documents: Prompts That Survive Sessions

What you’ll be able to do

You’ll be able to write a plan artifact that:

Forces clarity on scope, constraints, and references.
Produces verification steps (not just a task list).
Is sized so an LLM can execute it phase-by-phase without drifting.

TL;DR

A plan is a shared source of truth between you and the model.
Keep plans at the “what” level; keep “how” in prompt docs.
Every phase needs verification and a definition of done.
If a plan file would exceed ~200 lines, split it.
Always point to reference implementations by path.

What belongs in a plan (and what doesn’t)
A plan template you can paste
Sizing rules
Verification and definition of done
Verification
Gotchas

What belongs in a plan (and what doesn’t)

Plans work when they are explicit and boring.

Include:

Goals and non-goals.
Constraints and invariants.
Reference implementations (by path).
Phases in dependency order.
Verification for each phase.

Avoid:

Full code blocks.
Deep implementation detail.
“Make it better” language.

If you want the LLM to do a thing consistently across sessions, you need the thing written down.

A plan template you can paste

Create one plan file per phase for larger work.

# <Project> Plan

## Overview
<1 to 2 sentences about what we are building>

## Goals
- <Goal 1>
- <Goal 2>

## Non-goals
- <Explicitly out of scope>

## Constraints
- <Must follow reference style X>
- <Must not add dependencies>
- <Must keep backward compatibility>

## References
- <Path to reference implementation 1>
- <Path to reference implementation 2>

## Phase 1: <Name>
- [ ] <Task 1>
- [ ] <Task 2>

Verification:
- <Command>
- Expected: <Exit 0 / output contains X>

## Phase 2: <Name>
- [ ] <Task 1>

Verification:
- <Command>
- Expected: <...>

## Definition of done
- [ ] <All phases verified>
- [ ] <Tests pass>
- [ ] <Docs updated as needed>
- [ ] <No TODOs left behind>

## Risks / open questions
- <Open question 1>
- <Risk 1>

Sizing rules

You need the plan sized so the LLM can execute it without mixing unrelated changes.

Use these rules of thumb:

Small (hours to 1 to 2 days): one PLAN.md.
Medium (1 to 2 weeks): one PLAN.md with explicit phases.
Large (multi-week): plan/phase-1a-...md, plan/phase-1b-...md, etc.

When in doubt:

Split by file ownership (phases should avoid editing the same files).
Split by interface boundaries (one phase defines types/contracts; later phases implement).

Verification and definition of done

Make verification explicit in the plan so you don’t have to negotiate it mid-session.

Bad:

“Add tests”

Better:

“Add unit tests for Foo and run go test ./... (expected: exit 0).”

If your phase can’t be verified, it probably isn’t a phase yet.

Verification

If you follow the template above, you should be able to run something like:

# Example: lint and test gates.
# Replace with your repo's actual commands.

go test ./...

git diff --stat

Expected results:

go test exits 0.
git diff --stat shows only the files you intended to touch in this phase.

Gotchas

Plans that mix “what” and “how” become unreadable quickly.
If you don’t write down constraints, the LLM will invent defaults.
A “phase” that touches 30 files is usually multiple phases.

Continue -> Chapter 3: Prompt Documents: Prompts That Survive Sessions

Chapter 1: A Practical Workflow for LLM-Assisted Development That Doesn't Collapse After Day 2

Thu, 15 Jan 2026 09:00:00 -0500

Series: LLM Development Guide

Chapter 1 of 16

Next: Chapter 2: Planning: Plan Artifacts, Constraints, Definition of Done

What you’ll be able to do

You’ll be able to take a real development task and run an LLM through a repeatable loop that:

Survives breaks and multi-day work.
Produces output you can actually review.
Includes verification steps, not just code.
Creates a paper trail of decisions and assumptions.

TL;DR

Treat the LLM like a senior engineer who can execute quickly, but has no durable memory.
Externalize memory into three artifacts: plan/, prompts/, and work-notes/.
For large projects, add phase specification docs and phase implementation prompt docs (see Chapter 7).
Execute in small logical units, with verification and atomic commits.
If you’re fighting output quality, upgrade the model or shrink the scope.
Never paste secrets, PII, or production data.

Trust contract (read this before you paste anything)

Security: do not paste secrets, tokens, customer data, or anything you would not publish in a public repo.
Staleness: model names, pricing, and vendor policies change frequently. Treat examples as illustrative as of 2026-02-14.
Prereqs: you can run tests, review diffs, and explain the change in a code review.

Why most LLM-assisted development fails
The workflow
Quick start: copy/paste kit
Worked example: Helm chart from a reference chart
Verification
Failure modes

Why most LLM-assisted development fails

Most failures are workflow failures, not “prompting” failures:

You jump straight to implementation without a plan.
You don’t provide reference implementations, so you get generic output.
You lose context across sessions.
You don’t verify output.
You batch changes into giant commits that are hard to review or revert.

The workflow

This is the smallest loop I’ve found that stays stable after day 2:

Plan -> Prompt docs -> Work notes -> Execute -> Verify -> Commit

The artifacts are simple:

plan/: what we’re doing and how we’ll know it’s done.
prompts/: the reusable prompts aligned to phases.
work-notes/: state, decisions, assumptions, open questions, and a running session log.

When work scales to multi-week delivery, promote this into explicit phase specification docs plus phase implementation prompt files so scope and verification stay deterministic across sessions.

Quick start: copy/paste kit

This is intentionally minimal. It’s enough to make sessions resumable.

1) Create the artifact directories

mkdir -p plan prompts work-notes

2) Create a minimal plan

cat > plan/phase-1.md <<'MD'
# Phase 1: Plan

## Overview
<One sentence: what we are building>

## Goals
- <Goal 1>
- <Goal 2>

## Constraints
- <Constraint 1>
- <Constraint 2>

## Definition of done
- [ ] <Verification command + expected outcome>
- [ ] <Verification command + expected outcome>

## Out of scope
- <Thing we will not do in this phase>
MD

3) Create a phase prompt doc

cat > prompts/phase-1.md <<'MD'
# Phase 1 - Execution Prompt

## Role
You are a senior software engineer.

## Context
- Plan: plan/phase-1.md
- Work notes: work-notes/phase-1.md
- Reference implementation(s): <paths>

## Task
Implement the smallest logical unit that moves this phase forward.

## Constraints (follow exactly)
- MUST follow patterns in the reference implementation.
- MUST propose verification commands.
- MUST NOT change files outside this phase scope.

## Session management
As you work, update work-notes/phase-1.md:
- Decisions (with rationale)
- Assumptions
- Open questions
- Session log entry

## Commit discipline
After each logical unit:
1. Stop and summarize what changed.
2. Propose a commit message.
3. Wait for approval.
MD

4) Create work notes

cat > work-notes/phase-1.md <<'MD'
# Phase 1 - Work Notes

## Status
- [ ] Not started
- [ ] In progress
- [ ] Blocked
- [ ] Complete

## Decisions

## Assumptions

## Open questions

## Session log

## Commits
MD

Worked example: Helm chart from a reference chart

This example is about correctness and maintainability, not “Helm tricks”.

Scenario

Goal: create a new chart (for example, metrics-gateway) by following a reference chart (for example, event-processor) that already works in your environment.

The important part is the inputs you give the model. Don’t describe the reference chart. Paste it.

Reference inputs (what to paste)

Run these commands in your repo and paste their output into your planning prompt:

tree charts/event-processor/
sed -n '1,200p' charts/event-processor/Chart.yaml
sed -n '1,200p' charts/event-processor/values.yaml
sed -n '1,200p' charts/event-processor/templates/_helpers.tpl

Plan prompt (high-signal)

I want to create a new Helm chart for a service called `metrics-gateway`.

Reference implementation: charts/event-processor/ (this is our standard).
The new chart MUST follow the same structure and conventions.

Here are the reference inputs:
- tree output: ...
- Chart.yaml: ...
- values.yaml: ...
- templates/_helpers.tpl: ...

Please:
- Analyze the reference chart patterns.
- Produce a phased plan with verification steps.
- Call out any open questions you need answered (ports, probes, resources).

Execution prompt (phase-aligned)

Once you have the plan, generate prompt docs aligned to phases (scaffold, core templates, env overrides, validation). Each prompt should:

Name the deliverables.
Repeat constraints.
Include “update work notes” instructions.
Include verification commands.

What “done” looks like

A good end state is boring:

The new chart is structurally identical to the reference chart.
The values structure matches (so operators don’t re-learn config surfaces).
helm lint and helm template succeed.
Changes are split into reviewable commits.

Verification

You can verify you’re actually following the workflow, not just producing text:

# Artifacts exist.
test -d plan && test -d prompts && test -d work-notes

# A plan exists and is not empty.
test -s plan/phase-1.md

# A prompt doc exists.
test -s prompts/phase-1.md

# Work notes exist.
test -s work-notes/phase-1.md

If you are doing the Helm chart example:

helm lint charts/metrics-gateway
helm template charts/metrics-gateway >/tmp/metrics-gateway.rendered.yaml
test -s /tmp/metrics-gateway.rendered.yaml

Expected results:

The commands exit with code 0.
The rendered YAML file is non-empty.

Failure modes

Skipping references: you get generic output that doesn’t match your repo.
Skipping verification: you ship code that “looked right.”
Letting sessions run too long: context drifts and you lose earlier constraints.
Batching commits: review slows down and rollback gets painful.
Using the wrong model: cheap models are fine for boilerplate, but can burn hours on complex reasoning.

Continue -> Chapter 2: Planning: Plan Artifacts, Constraints, Definition of Done

Software-Engineering | Roy Gabriel

LLM Development Guide

Chapter 16: Worked Example: Converting an Ansible Playbook to a Go Temporal Workflow

What you’ll be able to do

TL;DR

Table of contents

Scenario

Reference inputs

Plan and phase structure

Implementation skeleton (Go)

Verification

Gotchas

Chapter 15: Worked Example: Creating a Helm Chart From a Reference Chart

What you’ll be able to do

TL;DR

Table of contents

Scenario

Reference inputs

Phase 1: Plan

Phase 2: Prompt docs

Phase 3: Execute in logical units

Strategy A (recommended): copy the reference chart, then adapt

Strategy B: scaffold from scratch, guided by the reference

Verification

Gotchas

Chapter 14: Building a Prompt Library: Governance + Quality Bar

What you’ll be able to do

TL;DR

Table of contents

Library structure

Prompt entry template

Contribution guidelines

Governance

Verification

Chapter 13: Templates + Checklists: The Copy/Paste Kit

What you’ll be able to do

TL;DR

Table of contents

Plan template

Prompt template

Phase spec template (large projects)

Phase implementation prompt template (large projects)

Work notes template

Session checklists

PR description template

Verification

Chapter 12: Team Collaboration: Handoffs, Shared Prompts, and Review

What you’ll be able to do

TL;DR

Table of contents

Handoff patterns

Mid-phase handoff

Phase boundary handoff

Shared prompt libraries

Review checklist

Verification

Chapter 11: Measuring Success: Solo + Team Metrics Without Fake Precision

What you’ll be able to do

TL;DR

Table of contents

What to measure

Solo baseline

Leading vs lagging indicators

Lightweight reporting template

Verification

Chapter 10: Stop Rules + Pitfalls: When to Upgrade, Bail, or Go Manual

What you’ll be able to do

TL;DR

Table of contents

Stop rules

Stop rule 1: tiny changes

Stop rule 2: you can’t review it

Stop rule 3: you’re fighting output quality

Stop rule 4: high-risk code needs extra caution

Top pitfalls

Recovery checklist

Verification

Chapter 9: Security & Sensitive Data: Sanitize, Don't Paste Secrets

What you’ll be able to do

TL;DR