From 748623d5927fa73f9c8a73699cf769e8f669f168 Mon Sep 17 00:00:00 2001 From: cskwork Date: Mon, 5 Oct 2026 07:29:08 +0900 Subject: [PATCH 1/2] feat: records written to be skimmed, bottom line first (v0.23.0) AGENTS.md rule 8 adapts the Attention-kind output style (github.com/alexgreensh/attention-span, AGPL-3.0; principles restated, no text copied). Reader parts (reports, gate requests, Human summaries, summary.md, the Goal line) lead with the bottom line and give each point as a bold arrow paragraph, so the bold alone carries the answer and every warning. Records open each section with its conclusion and state each fact once. Exact numbers, scoped conditions, warnings, verbatim output and every script-read line keep their form. Changed: a report used to start with a context paragraph; it now starts with the bottom line. Spec and plan Human summary templates ask for one bottom-line sentence plus five / three arrow points. No new file, axis, gate, or check. --- AGENTS.md | 32 ++++++++++++++++++---- README.ko.md | 2 ++ README.md | 2 ++ VERSION | 2 +- log/changelog-v0.23.0.md | 58 ++++++++++++++++++++++++++++++++++++++++ skills/2-spec/SKILL.md | 9 ++++--- skills/3-plan/SKILL.md | 7 ++--- templates/plan.md | 6 +++-- templates/spec.md | 15 ++++++----- templates/summary.md | 3 +++ 10 files changed, 115 insertions(+), 21 deletions(-) create mode 100644 log/changelog-v0.23.0.md diff --git a/AGENTS.md b/AGENTS.md index 68e73c1..5cad05a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -308,11 +308,33 @@ archives the feature to `.sdlc/archive//`. it), `harvest` (unmerged candidates), `index` (contents page). `--area ` covers every store in that folder, including features whose checkout is gone. Exit 0 found · 1 nothing · 2 usage/refusal. -8. **Speak plainly.** Every report, gate request, and question starts with - one short context paragraph (which stage, what happened before, what this - message is for), uses short active sentences and the project's own - vocabulary, and ends with the one decision or action the reader must - take. +8. **Speak plainly, bottom line first.** The reader's attention is the + scarce resource: what they skip was not delivered, however complete the + page. (Adapted from the Attention-kind style, + github.com/alexgreensh/attention-span.) Two tiers: + - **Reader parts** — every report, gate request, and question; the Human + summary of spec.md and plan.md; summary.md; intent.md's `Goal:` line. + The first sentence is the bottom line (the result, or the decision + asked), so a reader who stops there has it. Then one line of context + (which stage, what came before). Each further point is its own + paragraph, `**→ Lead-in.** rest`, a blank line between points; bold the + lead-in and the key number or decision, so the bold alone carries the + answer and every warning. One idea per block, short active sentences, + the project's own words; an unavoidable term gets a gloss of five words + or fewer. The one decision or blocking question comes last, and nothing + follows it. + - **Records** — evidence.md, the bodies of spec.md and plan.md, build + logs, handoff notes. Each section opens with its conclusion in one + line; one idea per line; a fact is written once and pointed at + afterwards (`evidence.md §n`, `R3`), never restated. No arrows or bold + added. + - **Both.** Numbers, thresholds, and scoped conditions stay exact ("only + accounts under 14 days old", not "new accounts"). A warning, risk, or + precondition is never cut for length. When there is more than a reader + can take in, give the one or two that matter in full and name the rest + with where it lives; never dump it, never drop it silently. Verbatim + output, `VERDICT` and `check:` lines, and the `- Field:` lines and + section headings the scripts read keep their exact form. 9. **Heartbeat.** `.sdlc/work//progress.md` holds exactly one line — `[ n/m] · · ` — overwritten, never appended: as soon as the slug dir exists, on stage diff --git a/README.ko.md b/README.ko.md index 95809dd..7b543ca 100644 --- a/README.ko.md +++ b/README.ko.md @@ -173,6 +173,8 @@ agent APPROVED: intent of claims-status (.sdlc/work/claims-status/intent.md) `init.sh`는 프로젝트 `.gitignore`에 루트에 고정된 한 줄, `/.sdlc`만 추가합니다. 그래서 애플리케이션을 클론해도 기록은 따라오지 않습니다. 피처가 열려 있는 동안 `status.sh`가 하트비트를 나이와 함께 `now →` 줄로 보여줍니다. +**훑어 읽도록 씁니다.** 사람이 읽는 부분(게이트 요청, spec과 plan의 Human summary, `summary.md`)은 결론을 첫 줄에 쓰고, 요점마다 `**→ 굵은 첫머리**` 문단으로 나눕니다. 그래서 굵은 글씨만 읽어도 답과 경고가 모두 잡힙니다. 기록 문서(evidence, plan 본문, 로그)는 섹션마다 결론을 먼저 쓰고 같은 사실을 두 번 쓰지 않습니다. 정확한 숫자, 적용 조건, 경고는 길이 때문에 빼지 않습니다. 규칙은 AGENTS.md 8번이며 [Attention-kind](https://github.com/alexgreensh/attention-span) 출력 스타일을 바탕으로 했습니다. + **기록을 어디에 둘지는 사용자가 정합니다.** 기본값은 프로젝트 작업 사본 안입니다. `init.sh . --area ~/knowledge`를 쓰면 `/-/`에 저장하고 `.sdlc`를 그곳으로 연결합니다. 체크아웃마다 저장소가 하나씩이라 워크트리 두 개가 승인을 공유하지 않습니다. 저장소에 쓰거나 게이트 판정을 보고하는 스크립트는 모두 `/PROJECT`에 다른 체크아웃이 적혀 있으면 거부하므로, 복사한 작업 사본이 원본의 피처를 열거나 닫을 수 없습니다. 읽기는 이 제약을 받지 않아 `tools/kb.sh show|search|list`는 그대로 동작합니다. 킷이 대신 옮겨 주는 것은 없고, **저장소 백업은 사용자의 몫입니다.** 킷 디렉터리에는 프레임워크만 남습니다. **지식은 제품 영역별로 정리됩니다.** 웹앱이면 제품 영역은 메뉴 하나이고 메뉴 경로(`학습 > 평가 > 제출`)로 부릅니다. 그 밖에는 모듈, API, 배치 작업, CLI 명령입니다. 제품 영역마다 페이지 `memory/areas/학습 - 평가 - 제출.md`가 한 장 있고, 개발자가 아니어도 읽을 수 있게 씁니다. 업무 정책 P1, P2…, 건수·비율·점수·차트를 보여주는 영역이면 통계 산정 N1, N2…, 동작 방식, 그 영역을 바꾼 피처마다 이력 한 행이 들어갑니다. 맨 아래 접힌 근거 블록에는 출처, 코드 위치, `Drive:` 줄이 있습니다. `Drive:` 줄은 사용자가 그 영역에 닿는 경로, 그 영역을 구동하는 명령이나 도구, 성공을 증명하는 최종 상태, 함정을 적습니다. ship 단계가 E2E 검사에서 이 줄을 harvest 후보로 올리고, 다음 verifier는 이 줄에서 출발합니다. 피처의 `summary.md`는 제품 영역을 적고, spec은 어떤 정책과 수치를 유지하거나 바꾸는지 밝히며, Side effects verifier가 나머지를 다시 확인합니다. diff --git a/README.md b/README.md index 1f3e527..3ed6e7d 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,8 @@ Per feature, inside the **target project**: `init.sh` adds one anchored line, `/.sdlc`, to the project's `.gitignore`, so a clone of the application does not carry the records. While a feature is open, `status.sh` shows its heartbeat as a `now →` line with its age. +**Written to be skimmed.** The parts a person reads (gate requests, the Human summary of spec and plan, `summary.md`) lead with the bottom line, then give each point as a `**→ bold lead-in**` paragraph, so the bold alone carries the answer and every warning. The records (evidence, plan body, logs) open each section with its conclusion and state each fact once. Exact numbers, scoped conditions, and warnings are never cut for length. The rules are AGENTS.md rule 8, adapted from the [Attention-kind](https://github.com/alexgreensh/attention-span) output style. + **Where the records live is your choice.** By default they sit in the project's working copy. `init.sh . --area ~/knowledge` puts them in `/-/` instead, with `.sdlc` linked to it: one store per checkout, so two worktrees never share approvals. Every script that writes to the store or reports a gate verdict refuses when `/PROJECT` names another checkout, so a copied working copy cannot open or close the original's features. Reading is not bound: `tools/kb.sh show|search|list` still works. Nothing is ever moved for you, and **the store is yours to back up**. The kit directory stays framework-only. **Knowledge is filed by product area.** For a web app an area is one menu, named by its menu path (`학습 > 평가 > 제출`); otherwise a module, API, job, or CLI command. Each area has one page, `memory/areas/학습 - 평가 - 제출.md`, written for a non-developer: business rules P1, P2…, figures N1, N2… when the area shows counts, rates, scores, or charts, how it works, and one history row per feature that changed it. A folded evidence block at the bottom holds sources, code locations, and a `Drive:` line: how a user reaches the area, the command or tool that drives it, the end state that proves it, and the traps. Ship harvests that line from the E2E check, and the next verifier starts from it. A feature's `summary.md` names its area, the spec states which rules and figures it keeps or changes, and the Side effects verifier re-checks the rest. diff --git a/VERSION b/VERSION index 2157409..ca222b7 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.22.0 +0.23.0 diff --git a/log/changelog-v0.23.0.md b/log/changelog-v0.23.0.md new file mode 100644 index 0000000..f2ae38e --- /dev/null +++ b/log/changelog-v0.23.0.md @@ -0,0 +1,58 @@ +# v0.23.0 — records written to be skimmed: bottom line first, bold carries the answer + +The documents the loop writes were complete but hard to read: a spec's Human +summary could be ten sentences with no bottom line, and a long plan restated +the same facts across sections. This release adapts the Attention-kind output +style (github.com/alexgreensh/attention-span) to the kit's artifacts. That +project is AGPL-3.0; nothing is copied from it, the principles are restated +in the kit's own words. No new file, axis, gate, or check; scripts read +nothing that changed. + +## Changes + +- **AGENTS.md rule 8 — "Speak plainly, bottom line first."** Two tiers. + *Reader parts* (reports, gate requests, questions, the Human summary of + spec.md and plan.md, summary.md, intent.md's Goal line): the first sentence + is the bottom line, then one line of context, then each point as a + `**→ Lead-in.** rest` paragraph whose bold alone carries the answer and + every warning; the decision or blocking question comes last. + *Records* (evidence.md, spec and plan bodies, logs, handoff notes): each + section opens with its conclusion, one idea per line, a fact written once + and pointed at afterwards; no arrows or bold added. *Both*: numbers, + thresholds, and scoped conditions stay exact; a warning is never cut for + length; breadth is named and pointed at, never dumped or silently dropped; + verbatim output and every line a script reads keep their exact form. +- **Changed from v0.22.0:** a report or gate request used to *start* with a + context paragraph. It now starts with the bottom line; context follows in + one line. +- **templates/spec.md, templates/plan.md** — the Human summary placeholder + asks for a one-sentence bottom line plus five (spec) or three (plan) + `**→**` points, instead of "ten short sentences" / "five short sentences". + skills/2-spec and skills/3-plan say the same. +- **templates/summary.md** — each section opens with its point in bold; the + `- Field:` lines kb.sh reads keep their form. +- **README.md, README.ko.md** — one paragraph, "Written to be skimmed". + +## Before → after (a spec Human summary) + +Before: eight unbroken sentences. The reader meets "drag handles", "the +ordering column", and "the export format" before learning that a decision +is being asked of them. + +After: + +> Teachers can re-order quiz questions by dragging them. +> +> **→ Students see the new order** from their next attempt; answers already +> submitted keep the order they were given in. +> +> **→ Reports and exports are unchanged.** +> +> **→ Decision needed:** quizzes with **more than 200 questions** would load +> slowly in the editor. Recommendation: allow re-ordering only below 200 +> for this release. + +## Upgrading + +Nothing to migrate. Artifacts written before v0.23.0 stay valid; the new +shape applies to what is written next. diff --git a/skills/2-spec/SKILL.md b/skills/2-spec/SKILL.md index 32d94de..394e8f5 100644 --- a/skills/2-spec/SKILL.md +++ b/skills/2-spec/SKILL.md @@ -26,10 +26,11 @@ Fill `templates/spec.md`. Rules: - **Human summary first.** The spec body is an agent-facing contract. The gate reviewer is a human — possibly one with no technical background. Write the top "Human summary" section so ANYONE can follow it (extends - hard rule 8): no code identifiers, no jargon (gloss an unavoidable term in the same - sentence), visible behavior rather than system internals — what problem, - what gets built, what stays unchanged, and each flagged concern as a - one-line decision with your recommendation. Test: would a non-developer + hard rule 8): the bottom line first, then `**→**` points whose bold alone + carries the summary; no code identifiers, no jargon (gloss an unavoidable + term in five words or fewer), visible behavior rather than system + internals — what problem, what gets built, what stays unchanged, and each + flagged concern as a one-line decision with your recommendation. Test: would a non-developer colleague understand every sentence? If not, rewrite. Write it LAST (after the adversarial pass), place it FIRST. - Every requirement cites the intent.md O-item it fulfils (`R1: … (O1)`). An diff --git a/skills/3-plan/SKILL.md b/skills/3-plan/SKILL.md index 14314ad..117124c 100644 --- a/skills/3-plan/SKILL.md +++ b/skills/3-plan/SKILL.md @@ -55,9 +55,10 @@ exploration stays out of the main context. Then fill `templates/plan.md`: record the verdict in the template's **Gate tier** section, with reasons. Run `/tools/tripwire.sh .sdlc/work//plan.md` and include its output in the adversary dispatch. -- **Human summary.** Five short sentences or fewer at the top, in plain words - a non-technical reader can follow: what changes, - the main risk, how it is proven. Write it last, place it first. +- **Human summary.** The bottom line in one sentence, then three `**→**` + points or fewer, in plain words a non-technical reader can follow: what + changes, the main risk, how it is proven (AGENTS.md rule 8). Write it last, + place it first. Constraints the code does not show (ownership, forbidden areas, deploy windows) are collected at the spec gate, not here. If a missing constraint diff --git a/templates/plan.md b/templates/plan.md index 254d8a5..dc5ffb1 100644 --- a/templates/plan.md +++ b/templates/plan.md @@ -4,8 +4,10 @@ ## Human summary (read this first) - + ## Gate tier diff --git a/templates/spec.md b/templates/spec.md index 3b65df9..fded344 100644 --- a/templates/spec.md +++ b/templates/spec.md @@ -5,14 +5,17 @@ ## Human summary (read this first) - +alone. AGENTS.md rule 8.> ## Requirements From 3ad190aee3dfa9afe01509ee023ddc662627505e Mon Sep 17 00:00:00 2001 From: cskwork Date: Mon, 5 Oct 2026 07:34:08 +0900 Subject: [PATCH 2/2] refactor: tighten rule 8 to one source, fix tier conflicts Rule 8 shrinks to three parts and the templates point at it instead of restating it; skills/2-spec is back to v0.22.0 and skills/3-plan points at the template. Fixes: the Goal line is a script-read field, not a styled part; evidence sections end in VERDICT lines, so only a section without one opens with its conclusion; summary.md keeps its fixed headings (bold lead per section, not arrow paragraphs); line one names that a decision is needed and the decision itself comes last, so it is not stated twice. --- AGENTS.md | 45 ++++++++++------------- README.ko.md | 2 +- README.md | 2 +- log/changelog-v0.23.0.md | 77 +++++++++++++++------------------------- skills/2-spec/SKILL.md | 9 +++-- skills/3-plan/SKILL.md | 6 ++-- templates/plan.md | 6 ++-- templates/spec.md | 16 +++------ templates/summary.md | 4 +-- 9 files changed, 62 insertions(+), 105 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5cad05a..554fd8f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -308,33 +308,24 @@ archives the feature to `.sdlc/archive//`. it), `harvest` (unmerged candidates), `index` (contents page). `--area ` covers every store in that folder, including features whose checkout is gone. Exit 0 found · 1 nothing · 2 usage/refusal. -8. **Speak plainly, bottom line first.** The reader's attention is the - scarce resource: what they skip was not delivered, however complete the - page. (Adapted from the Attention-kind style, - github.com/alexgreensh/attention-span.) Two tiers: - - **Reader parts** — every report, gate request, and question; the Human - summary of spec.md and plan.md; summary.md; intent.md's `Goal:` line. - The first sentence is the bottom line (the result, or the decision - asked), so a reader who stops there has it. Then one line of context - (which stage, what came before). Each further point is its own - paragraph, `**→ Lead-in.** rest`, a blank line between points; bold the - lead-in and the key number or decision, so the bold alone carries the - answer and every warning. One idea per block, short active sentences, - the project's own words; an unavoidable term gets a gloss of five words - or fewer. The one decision or blocking question comes last, and nothing - follows it. - - **Records** — evidence.md, the bodies of spec.md and plan.md, build - logs, handoff notes. Each section opens with its conclusion in one - line; one idea per line; a fact is written once and pointed at - afterwards (`evidence.md §n`, `R3`), never restated. No arrows or bold - added. - - **Both.** Numbers, thresholds, and scoped conditions stay exact ("only - accounts under 14 days old", not "new accounts"). A warning, risk, or - precondition is never cut for length. When there is more than a reader - can take in, give the one or two that matter in full and name the rest - with where it lives; never dump it, never drop it silently. Verbatim - output, `VERDICT` and `check:` lines, and the `- Field:` lines and - section headings the scripts read keep their exact form. +8. **Speak plainly, bottom line first** (adapted from Attention-kind, + github.com/alexgreensh/attention-span). What the reader skips was not + delivered. + - **Messages and Human summaries** (reports, gate requests, questions, + the Human summary of spec.md and plan.md): line one is the bottom line, + the result or that a decision is needed; one line of context (stage, + what came before); then one `**→ Lead-in.** rest` paragraph per point, + bold carrying the answer and every warning. The decision itself comes + last, and nothing follows it. + - **Records** (everything else): one idea per line; a fact stated once, + then pointed at (`R3`, `evidence.md §n`); a section without a verdict + line opens with its conclusion. summary.md sections open with their + point in bold. + - **Always:** short active sentences in the project's words; an + unavoidable term glossed in five words or fewer; numbers and scoped + conditions exact; a warning never cut for length. Too much at once: give + what matters most, then name the rest and where it lives. Verbatim + output and every line or heading a script reads keep their form. 9. **Heartbeat.** `.sdlc/work//progress.md` holds exactly one line — `[ n/m] · · ` — overwritten, never appended: as soon as the slug dir exists, on stage diff --git a/README.ko.md b/README.ko.md index 7b543ca..b3ac8ad 100644 --- a/README.ko.md +++ b/README.ko.md @@ -173,7 +173,7 @@ agent APPROVED: intent of claims-status (.sdlc/work/claims-status/intent.md) `init.sh`는 프로젝트 `.gitignore`에 루트에 고정된 한 줄, `/.sdlc`만 추가합니다. 그래서 애플리케이션을 클론해도 기록은 따라오지 않습니다. 피처가 열려 있는 동안 `status.sh`가 하트비트를 나이와 함께 `now →` 줄로 보여줍니다. -**훑어 읽도록 씁니다.** 사람이 읽는 부분(게이트 요청, spec과 plan의 Human summary, `summary.md`)은 결론을 첫 줄에 쓰고, 요점마다 `**→ 굵은 첫머리**` 문단으로 나눕니다. 그래서 굵은 글씨만 읽어도 답과 경고가 모두 잡힙니다. 기록 문서(evidence, plan 본문, 로그)는 섹션마다 결론을 먼저 쓰고 같은 사실을 두 번 쓰지 않습니다. 정확한 숫자, 적용 조건, 경고는 길이 때문에 빼지 않습니다. 규칙은 AGENTS.md 8번이며 [Attention-kind](https://github.com/alexgreensh/attention-span) 출력 스타일을 바탕으로 했습니다. +**훑어 읽도록 씁니다.** 게이트 요청과 Human summary는 결론을 첫 줄에 쓰고 요점마다 굵은 `→` 문단을 하나씩 둡니다. 굵은 글씨만 읽어도 답과 경고가 모두 잡히고, 기록 문서는 같은 사실을 한 번만 씁니다. AGENTS.md 8번 규칙이며 [Attention-kind](https://github.com/alexgreensh/attention-span)를 바탕으로 했습니다. **기록을 어디에 둘지는 사용자가 정합니다.** 기본값은 프로젝트 작업 사본 안입니다. `init.sh . --area ~/knowledge`를 쓰면 `/-/`에 저장하고 `.sdlc`를 그곳으로 연결합니다. 체크아웃마다 저장소가 하나씩이라 워크트리 두 개가 승인을 공유하지 않습니다. 저장소에 쓰거나 게이트 판정을 보고하는 스크립트는 모두 `/PROJECT`에 다른 체크아웃이 적혀 있으면 거부하므로, 복사한 작업 사본이 원본의 피처를 열거나 닫을 수 없습니다. 읽기는 이 제약을 받지 않아 `tools/kb.sh show|search|list`는 그대로 동작합니다. 킷이 대신 옮겨 주는 것은 없고, **저장소 백업은 사용자의 몫입니다.** 킷 디렉터리에는 프레임워크만 남습니다. diff --git a/README.md b/README.md index 3ed6e7d..f0dd79f 100644 --- a/README.md +++ b/README.md @@ -173,7 +173,7 @@ Per feature, inside the **target project**: `init.sh` adds one anchored line, `/.sdlc`, to the project's `.gitignore`, so a clone of the application does not carry the records. While a feature is open, `status.sh` shows its heartbeat as a `now →` line with its age. -**Written to be skimmed.** The parts a person reads (gate requests, the Human summary of spec and plan, `summary.md`) lead with the bottom line, then give each point as a `**→ bold lead-in**` paragraph, so the bold alone carries the answer and every warning. The records (evidence, plan body, logs) open each section with its conclusion and state each fact once. Exact numbers, scoped conditions, and warnings are never cut for length. The rules are AGENTS.md rule 8, adapted from the [Attention-kind](https://github.com/alexgreensh/attention-span) output style. +**Written to be skimmed.** Gate requests and Human summaries lead with the bottom line, then one bold `→` point each, so the bold alone carries the answer and every warning; records state each fact once. AGENTS.md rule 8, adapted from [Attention-kind](https://github.com/alexgreensh/attention-span). **Where the records live is your choice.** By default they sit in the project's working copy. `init.sh . --area ~/knowledge` puts them in `/-/` instead, with `.sdlc` linked to it: one store per checkout, so two worktrees never share approvals. Every script that writes to the store or reports a gate verdict refuses when `/PROJECT` names another checkout, so a copied working copy cannot open or close the original's features. Reading is not bound: `tools/kb.sh show|search|list` still works. Nothing is ever moved for you, and **the store is yours to back up**. The kit directory stays framework-only. diff --git a/log/changelog-v0.23.0.md b/log/changelog-v0.23.0.md index f2ae38e..f90a169 100644 --- a/log/changelog-v0.23.0.md +++ b/log/changelog-v0.23.0.md @@ -1,58 +1,37 @@ -# v0.23.0 — records written to be skimmed: bottom line first, bold carries the answer +# v0.23.0 — written to be skimmed: bottom line first -The documents the loop writes were complete but hard to read: a spec's Human -summary could be ten sentences with no bottom line, and a long plan restated -the same facts across sections. This release adapts the Attention-kind output -style (github.com/alexgreensh/attention-span) to the kit's artifacts. That -project is AGPL-3.0; nothing is copied from it, the principles are restated -in the kit's own words. No new file, axis, gate, or check; scripts read -nothing that changed. +Human summaries could run ten sentences with no bottom line, and long +records restated facts. AGENTS.md rule 8 now adapts the Attention-kind +output style (github.com/alexgreensh/attention-span, AGPL-3.0: principles +restated, no text copied). No new file, axis, gate, or check; no +script-read line changed. ## Changes -- **AGENTS.md rule 8 — "Speak plainly, bottom line first."** Two tiers. - *Reader parts* (reports, gate requests, questions, the Human summary of - spec.md and plan.md, summary.md, intent.md's Goal line): the first sentence - is the bottom line, then one line of context, then each point as a - `**→ Lead-in.** rest` paragraph whose bold alone carries the answer and - every warning; the decision or blocking question comes last. - *Records* (evidence.md, spec and plan bodies, logs, handoff notes): each - section opens with its conclusion, one idea per line, a fact written once - and pointed at afterwards; no arrows or bold added. *Both*: numbers, - thresholds, and scoped conditions stay exact; a warning is never cut for - length; breadth is named and pointed at, never dumped or silently dropped; - verbatim output and every line a script reads keep their exact form. -- **Changed from v0.22.0:** a report or gate request used to *start* with a - context paragraph. It now starts with the bottom line; context follows in - one line. -- **templates/spec.md, templates/plan.md** — the Human summary placeholder - asks for a one-sentence bottom line plus five (spec) or three (plan) - `**→**` points, instead of "ten short sentences" / "five short sentences". - skills/2-spec and skills/3-plan say the same. -- **templates/summary.md** — each section opens with its point in bold; the - `- Field:` lines kb.sh reads keep their form. -- **README.md, README.ko.md** — one paragraph, "Written to be skimmed". - -## Before → after (a spec Human summary) - -Before: eight unbroken sentences. The reader meets "drag handles", "the -ordering column", and "the export format" before learning that a decision -is being asked of them. - -After: - -> Teachers can re-order quiz questions by dragging them. +- **Rule 8, three parts.** Messages and Human summaries: the bottom line + first, one line of context, one `**→ Lead-in.**` paragraph per point, + the decision last. Records: one idea per line, each fact stated once + and then pointed at; a section without a verdict line opens with its + conclusion. Always: numbers and scoped conditions exact, warnings never + cut, verbatim output and script-read lines untouched. +- **Changed:** a message used to start with a context paragraph; it now + starts with the bottom line. +- **templates/spec.md, plan.md:** the Human summary is the bottom line plus + five (spec) or three (plan) `**→**` points, pointing at rule 8 instead of + restating it. skills/3-plan points at the template. +- **templates/summary.md:** each section opens with its point in bold. + +## Example (spec Human summary) + +> Teachers can re-order quiz questions by dragging them; one decision is +> needed. > -> **→ Students see the new order** from their next attempt; answers already -> submitted keep the order they were given in. +> **→ Students see the new order** from their next attempt; submitted +> answers keep theirs. > > **→ Reports and exports are unchanged.** > -> **→ Decision needed:** quizzes with **more than 200 questions** would load -> slowly in the editor. Recommendation: allow re-ordering only below 200 -> for this release. - -## Upgrading +> **→ Decision:** quizzes over **200 questions** load slowly in the editor. +> Recommend re-ordering only below 200 for now. -Nothing to migrate. Artifacts written before v0.23.0 stay valid; the new -shape applies to what is written next. +Nothing to migrate: older artifacts stay valid. diff --git a/skills/2-spec/SKILL.md b/skills/2-spec/SKILL.md index 394e8f5..32d94de 100644 --- a/skills/2-spec/SKILL.md +++ b/skills/2-spec/SKILL.md @@ -26,11 +26,10 @@ Fill `templates/spec.md`. Rules: - **Human summary first.** The spec body is an agent-facing contract. The gate reviewer is a human — possibly one with no technical background. Write the top "Human summary" section so ANYONE can follow it (extends - hard rule 8): the bottom line first, then `**→**` points whose bold alone - carries the summary; no code identifiers, no jargon (gloss an unavoidable - term in five words or fewer), visible behavior rather than system - internals — what problem, what gets built, what stays unchanged, and each - flagged concern as a one-line decision with your recommendation. Test: would a non-developer + hard rule 8): no code identifiers, no jargon (gloss an unavoidable term in the same + sentence), visible behavior rather than system internals — what problem, + what gets built, what stays unchanged, and each flagged concern as a + one-line decision with your recommendation. Test: would a non-developer colleague understand every sentence? If not, rewrite. Write it LAST (after the adversarial pass), place it FIRST. - Every requirement cites the intent.md O-item it fulfils (`R1: … (O1)`). An diff --git a/skills/3-plan/SKILL.md b/skills/3-plan/SKILL.md index 117124c..ed56b71 100644 --- a/skills/3-plan/SKILL.md +++ b/skills/3-plan/SKILL.md @@ -55,10 +55,8 @@ exploration stays out of the main context. Then fill `templates/plan.md`: record the verdict in the template's **Gate tier** section, with reasons. Run `/tools/tripwire.sh .sdlc/work//plan.md` and include its output in the adversary dispatch. -- **Human summary.** The bottom line in one sentence, then three `**→**` - points or fewer, in plain words a non-technical reader can follow: what - changes, the main risk, how it is proven (AGENTS.md rule 8). Write it last, - place it first. +- **Human summary.** In the template's shape (AGENTS.md rule 8). Write it + last, place it first. Constraints the code does not show (ownership, forbidden areas, deploy windows) are collected at the spec gate, not here. If a missing constraint diff --git a/templates/plan.md b/templates/plan.md index dc5ffb1..d77e83c 100644 --- a/templates/plan.md +++ b/templates/plan.md @@ -4,10 +4,8 @@ ## Human summary (read this first) - + ## Gate tier diff --git a/templates/spec.md b/templates/spec.md index fded344..175c8d3 100644 --- a/templates/spec.md +++ b/templates/spec.md @@ -5,17 +5,11 @@ ## Human summary (read this first) - + ## Requirements