Skip to content

Commit aa65430

Browse files
Clarify task history and document roles
1 parent bcf0cee commit aa65430

2 files changed

Lines changed: 31 additions & 5 deletions

File tree

CONSTITUTION.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -285,18 +285,20 @@ Rules in this section complement, and do not override,
285285

286286
11. **Done task cleanup**
287287
Keep done tasks in the task directory under the done status folder
288-
with a three-digit prefix based on order moved into done. This done
289-
numbering is independent from any three-digit backlog-order prefix.
290-
Delete them from the working tree after a release tag is created.
288+
with a three-digit prefix based on order moved into done. This done
289+
numbering is independent from any three-digit backlog-order prefix.
290+
Delete them from the working tree after a release tag is created.
291291

292292
## Context Preservation
293293

294294
- Re-read relevant task sections before implementation or whenever
295295
requirements are unclear.
296296
- Treat the active task or subtask as the working source of truth for
297297
the current work item.
298-
- Older task files are historical records and need not be
299-
retroactively updated when later tasks supersede them.
298+
- The active task or subtask does not need to be kept mutually
299+
consistent with already finished tasks. Older task files are
300+
historical working records and need not be retroactively updated when
301+
later tasks supersede them.
300302
- Keep only relevant task content in active context and avoid carrying
301303
unrelated content.
302304

README.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,30 @@ existing practices before any code is written. This is especially
5858
valuable in legacy systems: it prevents clean-room redesigns and makes
5959
incremental change safer.
6060

61+
## Document Roles and Lifetimes
62+
63+
Spec Loop uses more than one document type on purpose. They do not have
64+
the same job or the same lifetime.
65+
66+
- Task files are short-lived working artifacts for the next concrete
67+
slice of work. They exist to drive research, review, implementation,
68+
and testing of that slice.
69+
- ADRs capture durable decisions and the reasons behind them.
70+
- A glossary captures stable shared language across tasks, design,
71+
tests, code symbols, and commits.
72+
- Living project documents capture current truth that should remain
73+
useful after the task is accepted, such as technical shape,
74+
operations, or other stable project knowledge.
75+
76+
Historical task files do not need to be kept mutually consistent across
77+
time. The active task, however, should stay aligned with the glossary,
78+
living project documents, and implemented code for its scope.
79+
80+
If a project maintains a technical design document, its purpose is to
81+
describe the current technical shape, stable boundaries, and important
82+
flows. It should not become a second glossary or a catalog of transient
83+
implementation detail.
84+
6185
## Getting started
6286

6387
Apply the process to your repository.

0 commit comments

Comments
 (0)