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.
1---2name: gjkim-instruction3description: Create and maintain gjkim_instruction.md, the root document for a loop-engineering effort. The document holds only the minimum requirements and confirmed decisions, and deliberately leaves everything else open so that later iterations are not locked into early guesses. Use whenever the user mentions gjkim_instruction.md, a root document or root doc for a loop, loop engineering, starting a long-running agent loop on a goal, or asks to record a requirement or a confirmed decision for such an effort. Also use at the start of a loop iteration to check what is already decided versus still open.4---5
6# gjkim_instruction.md — Root Document for Loop Engineering
7
8## Why this document exists
9
10Loop engineering runs many short agent iterations against one long-lived
11goal. Each iteration starts with little context, so it needs one stable
12place that says what must be true and what has already been decided. That
13place is `gjkim_instruction.md`, kept at the root of the project the loop
14works on.
15
16The failure mode this document guards against is early decision lock-in.
17Whatever is written in the root document, every later iteration inherits as
18if it were a requirement. If unconfirmed details get written down — a
19library choice, a schema, a file layout that was only a first guess — wrong
20guesses become permanent and the loop loses the freedom to find better
21answers. So the document records only two kinds of content, and treats
22everything else as deliberately open.
23
24## What goes in
25
26- **Goal**: one or two sentences on what the effort must achieve.
27- **Minimum requirements**: the smallest set of outcomes that must hold
28 true for the effort to succeed. Outcome-level, not implementation-level.
29- **Non-goals**: outcomes the effort explicitly does not pursue, so
30 iterations do not drift into them. A non-goal is a confirmed "we are not
31 doing this", not merely something undecided — undecided things belong
32 under "Deliberately open".
33- **Confirmed decisions**: only decisions the user has explicitly
34 confirmed. Each entry carries the date it was confirmed and a one-line
35 why, so a later iteration can tell whether the reason still applies.
36- **Deliberately open** (optional): choices that are known to be undecided,
37 listed so iterations do not silently assume an answer. Listing an option
38 here does not endorse it.
39
40## What stays out
41
42- Implementation details that were not explicitly confirmed: libraries,
43 frameworks, schemas, file layouts, API shapes, deployment targets.
44- Task lists, progress logs, iteration status. Those belong in issues, PRs,
45 or iteration notes — the root document describes the destination, not the
46 journey.
47- Speculative designs or options under consideration. Mentioning them at
48 most under "Deliberately open", never as requirements or decisions.
49- Anything derivable from the code itself.
50
51Litmus test for requirement vs. detail: could two meaningfully different
52implementations both satisfy it? If only one implementation can, it is a
53detail — leave it out until the user confirms it as a decision.
54
55## Template
56
57Create the document at the project root, named exactly
58`gjkim_instruction.md`:
59
60```markdown
61# <effort name>
62
63Root document for loop engineering. Read this first in every iteration.
64Anything not written here is an open choice.
65
66## Goal
67
68<one or two sentences>
69
70## Minimum requirements
71
72- <outcome that must hold>
73
74## Non-goals
75
76- <outcome explicitly not pursued>
77
78## Confirmed decisions
79
80- <decision> — confirmed <YYYY-MM-DD>. Why: <one line>
81
82## Deliberately open
83
84- <choice known to be undecided; do not assume an answer>
85```
86
87Omit the "Non-goals" or "Deliberately open" section when there is nothing
88useful to warn about. Keep the whole document around one page; if it grows
89past that, details are leaking in — prune them.
90
91## Maintaining the document
92
93- Add a decision only when the user has explicitly confirmed it. "Leaning
94 toward", "probably", or "maybe" is not confirmation.
95- Record a non-goal only when the user has explicitly ruled it out. An
96 option nobody has decided on yet stays under "Deliberately open".
97- When an iteration must make a choice that is not in the document, make
98 the best local choice, record it in that iteration's PR or notes as
99 unconfirmed, and propose it to the user for confirmation. Do not write it
100 into the root document yet.
101- When a decision is reversed, replace the entry. The document describes
102 only the current state; git history holds the old one.
103- When updating, preserve existing requirements and decisions unless the
104 user explicitly changes them.
gjkim42