gjkim-instruction

gjkim_instruction.md — Root Document for Loop Engineering

Why this document exists

Loop engineering runs many short agent iterations against one long-lived goal. Each iteration starts with little context, so it needs one stable place that says what must be true and what has already been decided. That place is gjkim_instruction.md, kept at the root of the project the loop works on.

The failure mode this document guards against is early decision lock-in. Whatever is written in the root document, every later iteration inherits as if it were a requirement. If unconfirmed details get written down — a library choice, a schema, a file layout that was only a first guess — wrong guesses become permanent and the loop loses the freedom to find better answers. So the document records only two kinds of content, and treats everything else as deliberately open.

What goes in

• Goal: one or two sentences on what the effort must achieve.
• Minimum requirements: the smallest set of outcomes that must hold true for the effort to succeed. Outcome-level, not implementation-level.
• Non-goals: outcomes the effort explicitly does not pursue, so iterations do not drift into them. A non-goal is a confirmed "we are not doing this", not merely something undecided — undecided things belong under "Deliberately open".
• Confirmed decisions: only decisions the user has explicitly confirmed. Each entry carries the date it was confirmed and a one-line why, so a later iteration can tell whether the reason still applies.
• Deliberately open (optional): choices that are known to be undecided, listed so iterations do not silently assume an answer. Listing an option here does not endorse it.

What stays out

• Implementation details that were not explicitly confirmed: libraries, frameworks, schemas, file layouts, API shapes, deployment targets.
• Task lists, progress logs, iteration status. Those belong in issues, PRs, or iteration notes — the root document describes the destination, not the journey.
• Speculative designs or options under consideration. Mentioning them at most under "Deliberately open", never as requirements or decisions.
• Anything derivable from the code itself.

Litmus test for requirement vs. detail: could two meaningfully different implementations both satisfy it? If only one implementation can, it is a detail — leave it out until the user confirms it as a decision.

Template

Create the document at the project root, named exactly gjkim_instruction.md:

# <effort name>

Root document for loop engineering. Read this first in every iteration.
Anything not written here is an open choice.

## Goal

<one or two sentences>

## Minimum requirements

- <outcome that must hold>

## Non-goals

- <outcome explicitly not pursued>

## Confirmed decisions

- <decision> — confirmed <YYYY-MM-DD>. Why: <one line>

## Deliberately open

- <choice known to be undecided; do not assume an answer>

Omit the "Non-goals" or "Deliberately open" section when there is nothing useful to warn about. Keep the whole document around one page; if it grows past that, details are leaking in — prune them.

Maintaining the document

• Add a decision only when the user has explicitly confirmed it. "Leaning toward", "probably", or "maybe" is not confirmation.
• Record a non-goal only when the user has explicitly ruled it out. An option nobody has decided on yet stays under "Deliberately open".
• When an iteration must make a choice that is not in the document, make the best local choice, record it in that iteration's PR or notes as unconfirmed, and propose it to the user for confirmation. Do not write it into the root document yet.
• When a decision is reversed, replace the entry. The document describes only the current state; git history holds the old one.
• When updating, preserve existing requirements and decisions unless the user explicitly changes them.