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"

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