artificial productivity

artificial-productivity.md

Artificial Productivity

How to use these tihngs.

Like most people, I have had success with splitting things into a planning stage followed by an implementation stage. The implementation phase can be kind of synchronous/interactive, or can be a fully auto Ralph loop.

1. The Plan

Models have a limited context window. You want to use the plan phase to create a written document that another instance can easily follow. You want short, discrete tasks.

obra/superpowers

See the basic workflow -- brainstorming command and writing-plans command.

---

speckit

specify, plan, tasks, implement, in that order.

• The blog post -- Spec-driven development with AI: Get started with a new open source toolkit
• the repo

---

ed3dai/ed3d-plugins

See plan-and-execute command.

The plan is where the real 'work' happens. It's where you create your specs. The execution can usually switch to a cheaper model to save tokens.

• github.com/ed3dai/ed3d-plugins

These plugins are nice because they tend to give you specific instructions about what to do next, ie what to do after the plan phase -- things like /clear the context window, then tell the next machine to read the doc at abc/123.md. Note the chart for the plan-and-execute plugin:

Rough Idea
    │
    ▼
/start-design-plan  ──────► Design Document (committed to git)
    │
    ▼
/start-implementation-plan ──► Implementation Plan (phase files)
    │
    ▼
/execute-implementation-plan ──► Working Code (reviewed & committed)

Each step breaks it into pieces.

---

Plan Mode

Just type /plan. Instruct it to create a written list of tasks.

• How plan-mode and four slash commands turned Claude Code from unpredictable to dependable

---

The Ralph Loop

---

I highly recommend this video.

The name Ralph Wiggum Loop made me think it was a joke or something, but it's actually a kind of sophisticated protocol for optimizing the "context window". These things perform better with smaller amounts of context. The Ralph loop is about breaking down a problem into many small, atomic tasks that can be completed before the context window fills up too much.

compaction is the devil

It is a bash loop.

Good old bash.

It creates an agent, the agent aims to complete 1 task, then it kills the agent and starts a fresh one. That way the context never becomes overly saturated.

It has this basic form:

while :; do cat PROMPT.md | claude ; done

Of course there is more to it than that. The video is the best intro imo.

See this gist for a more realistic example of a loop, and also nearestnabors/ralph-wiggum-loop-starter

The Details

1. Define requirements

Have the agent interview you to determine the PRD document. I have a skill installed in my ~/.claude/skills directory at path ~/.claude/skills/prd/SKILL.md. That's how you install a skill. You just paste some markdown to a specific location in your home directory.

See skills/prd.

2. Further refine the PRD into discrete tasks

I've been using a ralph skill for this.

---

See Also

• nearestnabors/ralph-wiggum-loop-starter
• Navigator's Guild, a Discord server
• ed3d.net, Discord server
• Impeccable -- Design fluency for AI harnesses (this is good)
• Ralph Audit Loop (OpenAI Codex) "It runs a long-lived, autonomous, read-only code audit: the agent documents problems, but does not modify your repo."
• ralphworkflow.com

Writing

• github.com/ghuntley -- The Ralph Playbook.
• The Ralph Playbook 2
• everything is a ralph loop
• repomirror/repomirror.md
• github.com/nichoth/ralph -- an expanded form of this document
• github.com/snarktank/ralph

Video

• The Ralph Video
• "starts with a conversation"
• "It's a dance. This is how you build your specifications."
• "Today we're going to create specs"
• "How do you build specs? It's really simple"
• "This is now my pin"
• "Show you how you create specs"

Chatto

See Chatto is Robots

I believe that writing and maintaining good skills contributes 90% to your agentic engineering success

I’m going to describe some of my skills from the Chatto repository

Glossary and Architecture Inventory

for any non-trivial project, you have to establish some language

inventory of terms used in the project and what they refer to

Architecture/Feature Decision Records

The most useful skill by far is probably adr.
It instructs the agent to create and maintain a directory containing Architecture Decision Records

The fdr skill does the same thing, but for features (things the users can see and/or interact with.)

I start many larger features or architecture changes with hashing out an ADR or FDR together with the agent

Letting the Agent write Documentation

Large parts of Chatto’s documentation are written by my agents, with a technical-writing skill in place

Project Status

skill recall and activation have been significantly more reliable with the OpenAI models

I’m keeping the most important rules, very boringly, in my AGENTS.md files

One that has proven extremely valuable time and again [...] is a line or two describing the current status of the project

The extent to which this helps your agents make the right decisions about architectural changes, new features, or just the order in which to implement things is immeasurable.

Empowering the Agent with Data

When something unexpected happens, [...] I’m documenting these incidents, too: there is a postmortem skill that instructs the agent to maintain a log of postmortems, similar to the ADR and FDR inventories

Tests and Lints

I’ve made it a strict rule in my repository to cover every change, new feature, or bug fix with tests, and this test suite is the most important guardrail

For frontend development, I have instructed the agents to keep an inventory of all Svelte components in a Storybook project

See Storybook Workbench: audit vibe-coded UIs and find hidden bugs in hours

Code Reviews

the chatto-pr-checklist skill specifically instructs the agent to call out changes to any of the sturdy bits

---

the usual slop smell

New type of smell for 2025+

---

ADR vs FDR

FDR are about what the app does (from the perspective of the user), ADR about how it works (ie. from the perspective of the developer.)

A spec is four documents in a trench coat (link to bluesky post)

See the full report

---

Specs rot at four different speeds

A typical spec contains, all interleaved:

• Why we're building this — the product requirement.
• How the system is structured — the architectural decision.
• The order of operations — the implementation plan.
• What "done" looks like — the contract.

1. product requirements change frequently
2. architecture stays in put for years
3. implementation plan is done when the PR is merged

Documentation should be layered by lifetime, not by topic

---

1. product requirements

Keep them out of git. Use tickets, issue trackers.

2. Architectural Decisions

Should go in git. Captures why decisions were made. Use MADR.

3. Implementation plans

Ephemeral; should not be committed to git.

4. Contracts

This is interface-first design.

---

What this looks like in practice

Layer	Lives in	Lifetime	Who reads it
Product requirements	Ticket system	Churns constantly	Humans, mostly
Architectural decisions	Git (MADR)	Permanent, append-only	Humans + agents
Implementation plan	Agent context / scratch file	Dies with the PR	Agent, briefly
Contract	Integration test suite	Enforced by CI	CI, agents, humans