Skip to content

Commit 2d7d57a

Browse files
clkaoclaude
clkao
and
claude
committed
ideation: #144 schema/field-reference dedup — stage report with before/after and test plan
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent cb8893f commit 2d7d57a

1 file changed

Lines changed: 184 additions & 0 deletions

File tree

‎docs/plans/workflow-readme-schema-and-fields-deduplication.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,187 @@ Scope:
4141
- Edit the README template in the commission skill so future workflows ship with one representation.
4242
- Decide whether to retroactively fix `docs/plans/README.md` and any other already-commissioned workflows in the repo, or leave them.
4343
- Static test (or doc lint) asserting the emitted README does not duplicate field listings.
44+
45+
## Stage Report
46+
47+
### 1. Exact duplication identified
48+
49+
Three sections in the commissioned README carry overlapping field information:
50+
51+
**`## Schema` (lines 37-54 of `docs/plans/README.md`)** — a YAML block listing every frontmatter field with empty/default values:
52+
53+
```yaml
54+
---
55+
id:
56+
title: Human-readable name
57+
status: backlog
58+
source:
59+
started:
60+
completed:
61+
verdict:
62+
score:
63+
worktree:
64+
issue:
65+
pr:
66+
---
67+
```
68+
69+
**`### Field Reference` (lines 56-71)** — a table repeating the same 12 fields with Type and Description columns:
70+
71+
| Field | Type | Description |
72+
|-------|------|-------------|
73+
| `id` | string | Unique identifier... |
74+
| `title` | string | Human-readable task name |
75+
| ... | ... | ... |
76+
77+
**`## Task Template` (lines 157-173)** — another YAML block with the same 12 fields plus a body placeholder:
78+
79+
```yaml
80+
---
81+
id:
82+
title: Task name here
83+
status: backlog
84+
...
85+
---
86+
87+
Description of this task and what it aims to achieve.
88+
```
89+
90+
The `## Schema` YAML block and `## Task Template` YAML block contain the same fields. The `### Field Reference` table then describes those same fields a third time. A maintainer adding or renaming a field must update all three.
91+
92+
**Status: DONE**
93+
94+
### 2. Proposed resolution
95+
96+
Drop the YAML code block from `## Schema`. Keep the `### Field Reference` table (it carries richer information — types and descriptions). Keep the `## Task Template` section unchanged (it serves as a copy-paste template with body placeholder).
97+
98+
After the change, `## Schema` becomes a short intro sentence pointing readers to the table, and the YAML block is removed. The field list lives in exactly one place (the table), and the copy-paste shape lives in exactly one place (the template).
99+
100+
**Status: DONE**
101+
102+
### 3. Before/after for `skills/commission/SKILL.md`
103+
104+
The commission skill template (lines 241-259 of SKILL.md) currently emits:
105+
106+
**BEFORE** (lines 241-259):
107+
````markdown
108+
## Schema
109+
110+
Every {entity_label} file has YAML frontmatter with these fields:
111+
112+
```yaml
113+
---
114+
id:
115+
title: Human-readable name
116+
status: {first_stage}
117+
source:
118+
started:
119+
completed:
120+
verdict:
121+
score:
122+
worktree:
123+
issue:
124+
pr:
125+
{any domain-specific fields from {captain}'s answers}
126+
---
127+
```
128+
129+
### Field Reference
130+
````
131+
132+
**AFTER:**
133+
````markdown
134+
## Schema
135+
136+
Every {entity_label} file has YAML frontmatter. Fields are documented below; see **{Entity_label} Template** for a copy-paste starter.
137+
138+
### Field Reference
139+
````
140+
141+
The `### Field Reference` table, `## {Entity_label} Template` section, and everything else remain unchanged.
142+
143+
**Status: DONE**
144+
145+
### 4. Before/after for `docs/plans/README.md`
146+
147+
**BEFORE** (lines 37-55):
148+
```markdown
149+
## Schema
150+
151+
Every task file has YAML frontmatter with these fields:
152+
153+
```yaml
154+
---
155+
id:
156+
title: Human-readable name
157+
status: backlog
158+
source:
159+
started:
160+
completed:
161+
verdict:
162+
score:
163+
worktree:
164+
issue:
165+
pr:
166+
---
167+
```
168+
169+
### Field Reference
170+
```
171+
172+
**AFTER:**
173+
```markdown
174+
## Schema
175+
176+
Every task file has YAML frontmatter. Fields are documented below; see **Task Template** for a copy-paste starter.
177+
178+
### Field Reference
179+
```
180+
181+
The `### Field Reference` table (lines 58-71), `## Task Template` section (lines 157-173), and all other sections remain unchanged.
182+
183+
**Status: DONE**
184+
185+
### 5. Retroactive fix decision
186+
187+
Yes — fix `docs/plans/README.md` in this task. It is the only commissioned workflow in the repo (test fixtures under `tests/fixtures/` do not contain a `### Field Reference` table, so they are unaffected). Fixing the one live README alongside the template keeps them consistent and avoids a "template says X but the live file still says Y" state.
188+
189+
**Status: DONE**
190+
191+
### 6. Acceptance criteria
192+
193+
1. The `## Schema` section in `skills/commission/SKILL.md` does NOT contain a YAML code block (` ```yaml `). **Test:** `grep -c '```yaml' skills/commission/SKILL.md` within the `## Schema` section returns 0 matches between `## Schema` and `### Field Reference`.
194+
2. The `## Schema` section in `skills/commission/SKILL.md` still contains the `### Field Reference` table with all 12 standard fields. **Test:** grep for `### Field Reference` and count table rows.
195+
3. The `## {Entity_label} Template` section in `skills/commission/SKILL.md` is unchanged — still contains a YAML code block with field names and body placeholder. **Test:** grep for the template YAML block.
196+
4. The `## Schema` section in `docs/plans/README.md` does NOT contain a YAML code block. **Test:** same grep approach as criterion 1.
197+
5. The `## Schema` section in `docs/plans/README.md` includes a cross-reference to **Task Template**. **Test:** grep for `Task Template` in the Schema section.
198+
6. The `scripts/test_commission.py` "Schema" section check still passes. **Test:** the existing check `re.search("Schema", readme_text, re.IGNORECASE)` will continue to match since the `## Schema` heading is retained.
199+
200+
### 7. Test plan
201+
202+
**Static tests only. No E2E needed.** This is a template wording change with no behavioral impact on runtime.
203+
204+
- Add a static pytest test (`tests/test_commission_template.py` or within an existing static test file) that:
205+
- Reads `skills/commission/SKILL.md`
206+
- Asserts no ` ```yaml ` fence exists between the `## Schema` heading and the `### Field Reference` heading
207+
- Asserts `### Field Reference` heading exists
208+
- Asserts `## {Entity_label} Template` section contains a ` ```yaml ` fence
209+
- Verify `scripts/test_commission.py` still finds "Schema" and "Template" sections (existing check on line 144 searches for substrings; heading is retained, so no change needed).
210+
- Manual: confirm `docs/plans/README.md` reads correctly after edit.
211+
212+
Estimated cost: zero (static grep tests, no LLM invocation).
213+
214+
### 8. Scope boundary
215+
216+
**IN scope:**
217+
- Remove the YAML code block from `## Schema` in `skills/commission/SKILL.md` template
218+
- Replace it with a one-sentence intro pointing to the field reference table and entity template
219+
- Apply the same fix to `docs/plans/README.md`
220+
- Add a static test asserting no YAML block in the Schema section of the commission template
221+
222+
**OUT of scope:**
223+
- Changing the `### Field Reference` table content or column structure
224+
- Changing the `## {Entity_label} Template` section
225+
- Changing test fixture READMEs under `tests/fixtures/` (they don't have the duplication)
226+
- Reworking how the commission skill generates READMEs beyond this specific dedup
227+
- Any runtime or E2E test changes

0 commit comments

Comments
 (0)