lee-spec-kit 0.9.11 → 0.9.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +5 -0
- package/README.en.md +4 -2
- package/README.md +5 -3
- package/THIRD_PARTY_NOTICES.md +9 -0
- package/dist/index.js +2371 -714
- package/dist/index.js.map +1 -1
- package/package.json +5 -3
- package/resources/openwiki-skills/lee-spec-kit-technical-writing/.lee-spec-kit-skill.json +6 -0
- package/resources/openwiki-skills/lee-spec-kit-technical-writing/LICENSE.md +9 -0
- package/resources/openwiki-skills/lee-spec-kit-technical-writing/SKILL.md +62 -0
- package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/document-patterns.md +54 -0
- package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/information-architecture.md +53 -0
- package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/korean-style.md +71 -0
- package/templates/en/common/agents/skills/create-pr.md +2 -0
- package/templates/en/common/agents/skills/execute-task.md +2 -0
- package/templates/en/common/features/feature-base/decisions.md +1 -0
- package/templates/en/common/features/feature-base/plan.md +2 -0
- package/templates/ko/common/agents/skills/create-pr.md +2 -0
- package/templates/ko/common/agents/skills/execute-task.md +2 -0
- package/templates/ko/common/features/feature-base/decisions.md +1 -0
- package/templates/ko/common/features/feature-base/plan.md +2 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "lee-spec-kit",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.13",
|
|
4
4
|
"description": "Document-centered harness engineering toolkit for AI agent development",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -11,7 +11,9 @@
|
|
|
11
11
|
"files": [
|
|
12
12
|
"dist",
|
|
13
13
|
"templates",
|
|
14
|
-
"assets"
|
|
14
|
+
"assets",
|
|
15
|
+
"resources",
|
|
16
|
+
"THIRD_PARTY_NOTICES.md"
|
|
15
17
|
],
|
|
16
18
|
"keywords": [
|
|
17
19
|
"docs",
|
|
@@ -26,7 +28,7 @@
|
|
|
26
28
|
"workflow"
|
|
27
29
|
],
|
|
28
30
|
"author": "Lee Yoonsu",
|
|
29
|
-
"license": "
|
|
31
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
30
32
|
"engines": {
|
|
31
33
|
"node": ">=18.0.0"
|
|
32
34
|
},
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# License and attribution
|
|
2
|
+
|
|
3
|
+
The files in this `lee-spec-kit-technical-writing` skill directory are licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-nc-sa/4.0/).
|
|
4
|
+
|
|
5
|
+
They are an adapted and condensed work based on [Technical Writing](https://github.com/toss/technical-writing), copyright Viva Republica, Inc., which is distributed under the same CC BY-NC-SA 4.0 license.
|
|
6
|
+
|
|
7
|
+
Changes made for lee-spec-kit include reorganizing the source guidance into an agent skill, condensing it around code-grounded repository documentation, adding an OpenWiki-specific workflow and review checklist, and writing new adapter and evidence-boundary instructions. This notice does not imply endorsement by the original author.
|
|
8
|
+
|
|
9
|
+
The CC BY-NC-SA 4.0 license applies only to this skill directory. It does not replace the MIT license for lee-spec-kit source code or other package contents.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lee-spec-kit-technical-writing
|
|
3
|
+
description: Plan, write, and revise code-grounded OpenWiki documentation around a new developer's goal. Use for every reader-facing repository Knowledge page, including tutorials, how-to guides, explanations, references, and onboarding navigation.
|
|
4
|
+
license: CC-BY-NC-SA-4.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# OpenWiki Technical Writing
|
|
8
|
+
|
|
9
|
+
Make the repository easier to understand without weakening evidence or inventing facts.
|
|
10
|
+
|
|
11
|
+
## Plan the Knowledge route
|
|
12
|
+
|
|
13
|
+
1. Identify the new developer's immediate question.
|
|
14
|
+
2. Classify the page as a tutorial, how-to guide, explanation, or reference.
|
|
15
|
+
3. Build the smallest complete route around reader goals. Do not mirror the source tree or target a fixed page count.
|
|
16
|
+
4. Give each page one primary goal. Split a page when its sections serve different goals, but keep one short connected flow together.
|
|
17
|
+
5. When planning page jobs, copy the applicable writing instructions into every job. A later page worker must not have to infer the writing policy from the page path or neighboring output.
|
|
18
|
+
6. Include the reader question and document type in each job's purpose and instructions. The page title and outline must answer that question; a system name alone is not a reader goal.
|
|
19
|
+
|
|
20
|
+
Read [information-architecture.md](references/information-architecture.md) and [document-patterns.md](references/document-patterns.md) before submitting a repository page plan.
|
|
21
|
+
|
|
22
|
+
## Write each page
|
|
23
|
+
|
|
24
|
+
1. Gather tracked repository evidence before outlining the answer.
|
|
25
|
+
2. Put the reader's result, conclusion, or next action first.
|
|
26
|
+
3. Arrange sections in the order a new developer needs them.
|
|
27
|
+
4. Use specific headings, stable terminology, concrete subjects, and short sentences that carry one main idea.
|
|
28
|
+
5. Link prerequisite, neighboring, and next-step pages where they remove guesswork.
|
|
29
|
+
6. Add at least one descriptive Markdown source link to every generated reader-facing page except the index. Use `[label](repo://path)` or `[label](repo://path#Lx-Ly)` and prefer a stable line range when it points the reader to the relevant contract. Reserve `repo://` for tracked source files included in the repository fingerprint. Link another Knowledge page with a page-relative Markdown path, never `/openwiki/...` or `repo://openwiki/...` hrefs. Claim sidecars and inline code citations do not satisfy this requirement.
|
|
30
|
+
7. Resolve every Knowledge link to the exact planned path, including `.md`, but write its href relative to the current page directory. From `/openwiki/architecture/system.md` to `/openwiki/operations/workers.md`, use `../operations/workers.md`. Canonical `/openwiki/...` identifiers belong in plans and metadata; OpenWiki visualize 0.5.0 requires relative Markdown hrefs. Do not infer a shortened slug or extensionless alias.
|
|
31
|
+
8. Write Markdown URL targets with literal `/` characters. Never JSON-escape a Knowledge link as `\/openwiki\/...` or insert backslashes before slashes.
|
|
32
|
+
9. Finish the draft before editing it. In this second stage, choose one dominant document type, separate unrelated reader goals, and revise every paragraph for focus and natural terminology. Do not submit the first draft.
|
|
33
|
+
10. In the final stage, reconcile commands, conditions, exceptions, links and Claims with the edited prose, then submit the page. Check that every `repo://` target is a tracked regular file; directories belong in code notation or need a link to a relevant file inside them. Keep all three stages in the page job, without a separate model, score, or review artifact.
|
|
34
|
+
|
|
35
|
+
Technical accuracy is the hard constraint. If evidence is missing or conflicting, state the uncertainty instead of making the prose sound complete.
|
|
36
|
+
|
|
37
|
+
Unavailable input does not prove that a file is absent from the repository. Use available tracked-file metadata to check existence without opening excluded content. If that metadata is unavailable, describe the visibility limit instead of claiming absence. Do not relax ignore rules or read secrets to remove uncertainty.
|
|
38
|
+
|
|
39
|
+
## Load page-specific guidance
|
|
40
|
+
|
|
41
|
+
- Read [document-patterns.md](references/document-patterns.md) and use the pattern matching the assigned page type.
|
|
42
|
+
- Read [information-architecture.md](references/information-architecture.md) when changing page scope, order, headings, or cross-links.
|
|
43
|
+
- For Korean output, read [korean-style.md](references/korean-style.md) before drafting or revising any reader-facing prose, including frontmatter descriptions.
|
|
44
|
+
|
|
45
|
+
## Final review
|
|
46
|
+
|
|
47
|
+
- Can a new developer tell within the opening section what this page helps them do or understand?
|
|
48
|
+
- Does the page answer one primary question without hiding another document inside it?
|
|
49
|
+
- Are commands, paths, identifiers, boundaries, and runtime sequences exact and evidence-backed?
|
|
50
|
+
- Does every generated reader-facing page except the index contain at least one useful `repo://` Markdown source link?
|
|
51
|
+
- Does every page-relative Knowledge href resolve to the exact planned page, including `.md`, without a root-leading slash?
|
|
52
|
+
- Do Markdown URL targets use literal forward slashes without backslashes?
|
|
53
|
+
- Are prerequisites introduced before dependent concepts?
|
|
54
|
+
- Do headings describe their section instead of using vague labels such as “Details” or “Overview” repeatedly?
|
|
55
|
+
- Are important terms used consistently throughout the page and neighboring pages?
|
|
56
|
+
- Does every link help the reader prepare, understand context, or continue?
|
|
57
|
+
- Does the page distinguish current runtime facts from requirements, plans, and historical decisions?
|
|
58
|
+
- For Korean output, does the page keep the same reader-friendly speech level without falling back to declarative `-다` or formal `-습니다` prose?
|
|
59
|
+
|
|
60
|
+
## License boundary
|
|
61
|
+
|
|
62
|
+
This adapted skill is separately licensed under CC BY-NC-SA 4.0. See [LICENSE.md](LICENSE.md) for attribution and scope.
|
package/resources/openwiki-skills/lee-spec-kit-technical-writing/references/document-patterns.md
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Document patterns
|
|
2
|
+
|
|
3
|
+
Choose the pattern from the reader's goal, not from the source files available.
|
|
4
|
+
|
|
5
|
+
## Tutorial
|
|
6
|
+
|
|
7
|
+
Use when a new developer needs guided experience.
|
|
8
|
+
|
|
9
|
+
1. State the result they will reach.
|
|
10
|
+
2. List only required prerequisites.
|
|
11
|
+
3. Present a safe, reproducible sequence.
|
|
12
|
+
4. Show checkpoints that confirm progress.
|
|
13
|
+
5. End with the next useful concept or task.
|
|
14
|
+
|
|
15
|
+
## How-to guide or troubleshooting
|
|
16
|
+
|
|
17
|
+
Use when the reader has a concrete task or failure.
|
|
18
|
+
|
|
19
|
+
1. Name the goal or symptom precisely.
|
|
20
|
+
2. State assumptions and required state.
|
|
21
|
+
3. Give ordered actions with observable results.
|
|
22
|
+
4. Explain important branches and recovery steps.
|
|
23
|
+
5. Link deeper explanations instead of interrupting the procedure.
|
|
24
|
+
|
|
25
|
+
## Reference
|
|
26
|
+
|
|
27
|
+
Use when the reader needs exact facts during work.
|
|
28
|
+
|
|
29
|
+
1. Define scope and version assumptions.
|
|
30
|
+
2. Organize entries predictably.
|
|
31
|
+
3. Keep fields, paths, commands, defaults, and constraints exact.
|
|
32
|
+
4. Use tables only when repeated fields are genuinely easier to compare.
|
|
33
|
+
5. Add examples that clarify the contract without replacing it.
|
|
34
|
+
|
|
35
|
+
## Explanation
|
|
36
|
+
|
|
37
|
+
Use when the reader needs a mental model.
|
|
38
|
+
|
|
39
|
+
1. Lead with the core idea or boundary.
|
|
40
|
+
2. Connect components through cause, data flow, or ownership.
|
|
41
|
+
3. Explain why the structure exists only when repository evidence supports it.
|
|
42
|
+
4. Separate current behavior from requirements and historical decisions.
|
|
43
|
+
5. End with practical implications for navigation or change.
|
|
44
|
+
|
|
45
|
+
One page may contain a small supporting section of another type, but one pattern should remain dominant.
|
|
46
|
+
|
|
47
|
+
Use goal-oriented titles when they help the reader choose a page:
|
|
48
|
+
|
|
49
|
+
- tutorial: “Start CopySinger locally”;
|
|
50
|
+
- how-to: “Choose tests for a change”;
|
|
51
|
+
- explanation: “Understand job leases and recovery”;
|
|
52
|
+
- reference: “Environment variables”.
|
|
53
|
+
|
|
54
|
+
Do not force an action title on a reference page when a stable lookup noun is clearer.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Information architecture
|
|
2
|
+
|
|
3
|
+
Design the page around the reader's route through the repository.
|
|
4
|
+
|
|
5
|
+
## Start from the reader's purpose
|
|
6
|
+
|
|
7
|
+
Use these four document types as the default navigation model:
|
|
8
|
+
|
|
9
|
+
- `tutorials/`: a guided learning path that reaches a working result;
|
|
10
|
+
- `how-tos/`: a concrete task or problem to finish;
|
|
11
|
+
- `explanations/`: a mental model, boundary, or design reason to understand;
|
|
12
|
+
- `reference/`: exact values, contracts, states, commands, or paths to look up.
|
|
13
|
+
|
|
14
|
+
OpenWiki generates directory indexes itself; do not include those indexes in a page plan or edit their control fields. Use the required `/openwiki/quickstart.md` as the human entrypoint and group its navigation links by reader purpose. Use a system-oriented group such as `architecture/` or `operations/` only when it is clearer for the reader than the four default types; do not create both groupings for the same content.
|
|
15
|
+
|
|
16
|
+
Before choosing a path, record the reader question and document type in the page job. “How do I start the app locally?” is a tutorial; “How do I recover a failed job?” is a how-to; “Why does a worker need a lease?” is an explanation; “Which values configure a worker?” is a reference. Separate these goals even when they share source files. Pass this classification to the page worker through the job purpose and instructions, without requiring a new frontmatter schema.
|
|
17
|
+
|
|
18
|
+
This is a planning preference, not a page-count target. A small repository may need only a few pages. A large repository should split pages only where the reader's goal, prerequisite, or evidence ownership changes.
|
|
19
|
+
|
|
20
|
+
## Scope one primary topic
|
|
21
|
+
|
|
22
|
+
A page should resolve one main question. Split material when sections serve different goals, require different prerequisites, or need to be maintained by different evidence.
|
|
23
|
+
|
|
24
|
+
Keep closely related facts together. Do not split a short, sequential explanation merely to produce more pages.
|
|
25
|
+
|
|
26
|
+
## Order by reader need
|
|
27
|
+
|
|
28
|
+
Use this default sequence when it fits:
|
|
29
|
+
|
|
30
|
+
1. What this page explains and why it matters
|
|
31
|
+
2. Prerequisites or surrounding context
|
|
32
|
+
3. Main components or steps
|
|
33
|
+
4. Boundaries, exceptions, and failure behavior
|
|
34
|
+
5. Where to go next
|
|
35
|
+
|
|
36
|
+
Put the value or conclusion before background that only makes sense afterward. Introduce a term before relying on it.
|
|
37
|
+
|
|
38
|
+
## Use informative headings
|
|
39
|
+
|
|
40
|
+
Headings should let a reader predict the section's content. Prefer “How a vocal analysis job reaches the worker” over “Runtime flow”. Keep sibling headings grammatically parallel when they represent comparable concepts.
|
|
41
|
+
|
|
42
|
+
## Build useful routes
|
|
43
|
+
|
|
44
|
+
Link only when it reduces navigation work:
|
|
45
|
+
|
|
46
|
+
- prerequisite: what the reader must know first;
|
|
47
|
+
- context: a related boundary or concept;
|
|
48
|
+
- next step: where the reader can continue a task;
|
|
49
|
+
- evidence: the tracked file supporting a factual claim.
|
|
50
|
+
|
|
51
|
+
Use descriptive link text. Avoid unexplained chains of “here”, raw host paths, or duplicate links that lead to the same destination.
|
|
52
|
+
|
|
53
|
+
Keep canonical `/openwiki/...md` paths for planning and page identity. In Markdown, use links relative to the current page: `../quickstart.md` from a one-level-deep page, or `../operations/workers.md` between sibling sections. This lets OpenWiki visualize resolve the intended relationship. Do not add unrelated links or duplicate indexes solely to make the graph connected.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Korean technical style
|
|
2
|
+
|
|
3
|
+
Write Korean that reads naturally while preserving code-level precision.
|
|
4
|
+
|
|
5
|
+
## Keep a reader-friendly voice
|
|
6
|
+
|
|
7
|
+
- Use `해요체` for explanations: `사용해요`, `확인할 수 있어요`, `경계예요`.
|
|
8
|
+
- Use `-하세요` when the reader needs to act: `명령을 실행하세요`, `상태를 확인하세요`.
|
|
9
|
+
- Do not fall back to declarative `-다` prose or formal `-습니다` prose. Do not mix speech levels to vary sentence endings.
|
|
10
|
+
- Keep warnings direct and respectful. State the risk, then tell the reader what to do.
|
|
11
|
+
- Preserve literal identifiers and quoted runtime text even when their wording does not follow this voice.
|
|
12
|
+
|
|
13
|
+
## Prefer direct sentences
|
|
14
|
+
|
|
15
|
+
- Put the actual actor in the subject when ownership matters.
|
|
16
|
+
- Use a concrete verb instead of turning an action into an abstract noun.
|
|
17
|
+
- Keep one main idea per sentence. Split a sentence when conditions and results compete for attention.
|
|
18
|
+
- Remove framing such as “살펴보겠습니다” when the content can begin directly.
|
|
19
|
+
- Avoid opening with “이 문서는 … 설명해요” when the result or problem can be stated directly.
|
|
20
|
+
- Prefer specific paths, states, and outcomes over vague words such as “관련”, “처리”, or “부분”.
|
|
21
|
+
|
|
22
|
+
## Write titles for scanning
|
|
23
|
+
|
|
24
|
+
- Use a concrete goal or concept rather than a stack of nouns joined with punctuation.
|
|
25
|
+
- For a tutorial or how-to, prefer `시작하기`, `변경하기`, `찾기`, or `해결하기`.
|
|
26
|
+
- For an explanation, prefer `이해하기` when it makes the reader's purpose clearer.
|
|
27
|
+
- For a reference, a stable noun title such as `환경 변수` or `작업 상태` is often clearer than an artificial action title.
|
|
28
|
+
|
|
29
|
+
## Keep terms stable
|
|
30
|
+
|
|
31
|
+
Use Korean for ordinary explanatory words: `worker` → `워커`, `ownership` → `소유권`, `lifecycle` → `수명 주기`, `focused test` → `변경 범위 테스트`, `persist` → `저장`, `retry` → `재시도`. These examples apply to prose, not identifiers: keep `leaseOwner`, `MixingJob`, `pnpm test`, product names, and exact API fields unchanged. Explain an unfamiliar term once, then use the same wording. Do not translate an identifier merely to make a sentence look more Korean.
|
|
32
|
+
|
|
33
|
+
For example, prefer “워커는 작업의 소유권을 확인한 뒤 결과를 저장해요” over “worker는 job ownership을 확인한 뒤 result를 persist해요”. Both sentences must still be supported by the same source evidence.
|
|
34
|
+
|
|
35
|
+
Choose one Korean term for each concept and reuse it. Keep identifiers, commands, paths, model names, and public API names unchanged. Add a short Korean explanation the first time an unfamiliar English term appears; do not alternate translations afterward.
|
|
36
|
+
|
|
37
|
+
## Edit paragraph density
|
|
38
|
+
|
|
39
|
+
Give each paragraph one point. Start with the behavior or result, then explain its condition or reason. When a paragraph moves from setup commands to runtime theory or troubleshooting, move that material to its own section or link to the corresponding planned page. Use a table for exact values and an ordered list for dependent actions. Do not remove exceptions, limits, or failure behavior just to shorten the text, and do not split one connected idea to satisfy a sentence-count target.
|
|
40
|
+
|
|
41
|
+
## Control density
|
|
42
|
+
|
|
43
|
+
Use paragraphs for a connected explanation, ordered lists for sequences, bullets for independent choices, and tables for repeated comparisons. Do not turn every sentence into a bullet. Put conditions before an action only when the reader must check them first.
|
|
44
|
+
|
|
45
|
+
## Make relationships explicit
|
|
46
|
+
|
|
47
|
+
Name what changed, what caused it, and what observes the result. Avoid omitted subjects when two services, processes, or documents could be the actor. State whether a described rule is a current code fact, durable requirement, active plan, or historical decision.
|
|
48
|
+
|
|
49
|
+
## Read once for rhythm
|
|
50
|
+
|
|
51
|
+
After checking facts, read the page as prose. Vary sentence structure without changing speech level, remove unnecessary passive forms, and shorten stacked modifiers. Do not trade exact meaning for variety.
|
|
52
|
+
|
|
53
|
+
## Rewrite dense repository prose
|
|
54
|
+
|
|
55
|
+
Before:
|
|
56
|
+
|
|
57
|
+
> 이 문서는 시스템 경계와 요청 표면을 설명한다. 브라우저 요청은 서버에서 처리되며 작업은 큐에 기록된다.
|
|
58
|
+
|
|
59
|
+
After:
|
|
60
|
+
|
|
61
|
+
> 짧은 웹 요청과 오래 걸리는 작업을 분리해요. 서버는 작업을 큐에 기록하고 바로 응답해요. 워커가 남은 처리를 이어가요.
|
|
62
|
+
|
|
63
|
+
Before:
|
|
64
|
+
|
|
65
|
+
> 환경 변수 설정 및 데이터베이스 마이그레이션 수행
|
|
66
|
+
|
|
67
|
+
After:
|
|
68
|
+
|
|
69
|
+
> 로컬 데이터베이스 준비하기
|
|
70
|
+
|
|
71
|
+
The rewrite changes presentation, not facts. Keep exact commands, identifiers, limits, states, and failure behavior grounded in repository evidence.
|
|
@@ -19,6 +19,8 @@ Execution-state SSOT is the feature-local `pr.md`.
|
|
|
19
19
|
|
|
20
20
|
The Pre-PR subagent must always run this minimum baseline. Do not depend on a named review skill.
|
|
21
21
|
|
|
22
|
+
Review Curated Documentation Impact evidence, including NONE. For each discovered discrepancy, verify a completed correction or a real follow-up task/Feature/issue with document paths, evidence, the unresolved question, and the deferral reason. A residual-risk note alone is not follow-up tracking. Report missing disposition as a finding; do not infer product intent from code or generated Knowledge. Existing review-round and approval policies still apply.
|
|
23
|
+
|
|
22
24
|
When `workflow-stage --json` returns `nextAction.executor: subagent`, delegate the review to a fresh, read-only subagent. `model: inherit` means inheriting the current model; any other value is used as the subagent model override. If that model is unavailable, follow `onUnavailable` (`inherit` or `error`).
|
|
23
25
|
|
|
24
26
|
1. Review alignment with `spec.md` / `plan.md` / `tasks.md` and confirm implementation still matches the original goal.
|
|
@@ -34,6 +34,8 @@ Use the active feature folder as the execution SSOT.
|
|
|
34
34
|
|
|
35
35
|
## 3. Keep docs in sync
|
|
36
36
|
|
|
37
|
+
Do not close a discovered documentation discrepancy with a decisions.md note alone. For an unambiguous factual error within approved scope, declare UPDATE/ADD and link a task Docs target. If product intent or scope expansion needs confirmation, record the conflicting document paths and evidence, the question to resolve, the deferral reason, and a real follow-up task/Feature/issue reference. Never invent identifiers or approvals. If creating the tracking item needs approval, do not report resolution before user confirmation. Explain in NONE evidence whether no known discrepancy remains or a remaining discrepancy is tracked by that follow-up. Never delete unimplemented PRD requirements merely to match code or OpenWiki.
|
|
38
|
+
|
|
37
39
|
- `spec.md`: update when user-visible scope or acceptance criteria change
|
|
38
40
|
- `plan.md`: update when architecture, file structure, or test strategy changes
|
|
39
41
|
- `decisions.md`: record non-obvious decisions, trade-offs, compatibility behavior, and user-requested behavior changes
|
|
@@ -12,6 +12,7 @@ If unmanaged docs artifacts exist outside the canonical docs surface (for exampl
|
|
|
12
12
|
Recording principles:
|
|
13
13
|
|
|
14
14
|
- Prefer `npx lee-spec-kit decision add <feature-ref> --title "..." --context "..." --decision "..." --rationale "..." --evidence "..."` when creating a new ADR.
|
|
15
|
+
- Append manual entries after the last ADR in D001 → D002 order, never before the document guidance, and preserve existing IDs. Update the same ADR's Trace/Evidence for reruns and verification results; create a new ADR only for a new choice or scope change.
|
|
15
16
|
- Every ADR must capture both **Decision (what was chosen)** and **Trace (how it was evaluated and validated)**.
|
|
16
17
|
- Use fixed timing checkpoints:
|
|
17
18
|
- Task start (`[TODO] -> [DOING]`): add 1-3 lines for `Context/Constraints` and `Trace (initial hypothesis)`
|
|
@@ -51,6 +51,8 @@ src/
|
|
|
51
51
|
|
|
52
52
|
## Curated Documentation Impact
|
|
53
53
|
|
|
54
|
+
Do not close a discovered documentation discrepancy with a decisions.md note alone. For an unambiguous factual error within approved scope, declare UPDATE/ADD and link a task Docs target. If product intent or scope expansion needs confirmation, record the conflicting document paths and evidence, the question to resolve, the deferral reason, and a real follow-up task/Feature/issue reference. Never invent identifiers or approvals. If creating the tracking item needs approval, do not report resolution before user confirmation. Explain in NONE evidence whether no known discrepancy remains or a remaining discrepancy is tracked by that follow-up. Never delete unimplemented PRD requirements merely to match code or OpenWiki.
|
|
55
|
+
|
|
54
56
|
> Complete this assessment even when every decision is `NONE`. `NONE` means the surface was reviewed and no human-owned project document needs to change. Generated OpenWiki synchronization is evaluated separately.
|
|
55
57
|
|
|
56
58
|
- **Schema**: 2
|
|
@@ -19,6 +19,8 @@ Pull Request를 생성할 때 따르는 가이드입니다.
|
|
|
19
19
|
|
|
20
20
|
Pre-PR 리뷰에서 서브에이전트가 항상 수행하는 최소 기준입니다. 리뷰 스킬 이름에 의존하지 않습니다.
|
|
21
21
|
|
|
22
|
+
Curated Documentation Impact의 NONE을 포함한 근거를 검토합니다. 발견한 불일치마다 수정 완료 또는 실제 후속 task/Feature/issue 연결을 확인하고 문서 경로·근거·미해결 질문·보류 이유를 점검합니다. 잔여 위험 문구만으로는 후속 추적이 아닙니다. 처리 누락은 finding으로 보고하며 코드나 파생 Knowledge로 제품 의도를 추정하지 않습니다. 기존 리뷰 횟수와 승인 정책은 그대로 적용합니다.
|
|
23
|
+
|
|
22
24
|
`workflow-stage --json`의 `nextAction.executor`가 `subagent`이면 fresh context의 읽기 전용 서브에이전트에게 리뷰를 위임합니다. `model: inherit`은 현재 모델을 상속한다는 뜻이며, 그 외 값은 서브에이전트 생성 시 모델 override로 사용합니다. 지정 모델을 사용할 수 없으면 `onUnavailable` 정책(`inherit` 또는 `error`)을 따릅니다.
|
|
23
25
|
|
|
24
26
|
1. `spec.md` / `plan.md` / `tasks.md` 기준으로 변경 범위 정합성을 확인하고, 구현이 원래 목적에 맞는지 점검합니다.
|
|
@@ -34,6 +34,8 @@
|
|
|
34
34
|
|
|
35
35
|
## 3. 문서 동기화
|
|
36
36
|
|
|
37
|
+
발견한 문서 불일치는 `decisions.md`에만 남기고 종료하지 않습니다. 현재 사실의 명백한 오류가 승인 범위 안에 있으면 `UPDATE`/`ADD`와 task `Docs`로 연결합니다. 제품 의도 확인이나 범위 확장이 필요하면 충돌한 문서 경로·근거, 확인할 질문, 보류 이유와 실제 후속 task/Feature/issue 참조를 기록합니다. 없는 번호나 승인을 만들지 않습니다. 추적 항목 생성에 승인이 필요하면 사용자 확인 전 해결된 것으로 기록하지 않습니다. `NONE`의 근거에는 알려진 불일치가 없거나, 남은 불일치가 해당 후속 항목으로 추적되고 있음을 설명합니다. 코드나 OpenWiki에 맞추기 위해 미구현 PRD 요구를 삭제하지 않습니다.
|
|
38
|
+
|
|
37
39
|
- `spec.md`: 사용자-visible scope 또는 acceptance criteria가 바뀌면 갱신합니다
|
|
38
40
|
- `plan.md`: 아키텍처, 파일 구조, 테스트 전략이 바뀌면 갱신합니다
|
|
39
41
|
- `decisions.md`: 비자명한 결정, 트레이드오프, 호환성 처리, 사용자 요청으로 바뀐 동작을 기록합니다
|
|
@@ -12,6 +12,7 @@ canonical docs surface 밖의 unmanaged docs 산출물(예: `docs/plans/*`, `doc
|
|
|
12
12
|
기록 원칙:
|
|
13
13
|
|
|
14
14
|
- 새 ADR 생성에는 `npx lee-spec-kit decision add <feature-ref> --title "..." --context "..." --decision "..." --rationale "..." --evidence "..."` 사용을 우선하세요.
|
|
15
|
+
- 수동 작성도 마지막 ADR 뒤에 추가해 D001 → D002 순서를 유지하세요. 문서 안내문 앞에 삽입하거나 기존 ID를 재번호화하지 마세요. 같은 결정의 재실행·검증 결과는 해당 ADR의 Trace/Evidence를 갱신하고, 새 선택이나 범위 변경일 때만 새 ADR을 만드세요.
|
|
15
16
|
- 모든 ADR은 **Decision(무엇을 선택했는가)** + **Trace(어떻게 고민했고 무엇을 확인했는가)** 를 함께 남깁니다.
|
|
16
17
|
- 작성 타이밍을 고정합니다.
|
|
17
18
|
- 태스크 시작(`[TODO] -> [DOING]`): `Context/Constraints`와 `Trace(초기 가설)`를 1~3줄로 먼저 기록
|
|
@@ -51,6 +51,8 @@ src/
|
|
|
51
51
|
|
|
52
52
|
## Curated Documentation Impact
|
|
53
53
|
|
|
54
|
+
발견한 문서 불일치는 `decisions.md`에만 남기고 종료하지 않습니다. 현재 사실의 명백한 오류가 승인 범위 안에 있으면 `UPDATE`/`ADD`와 task `Docs`로 연결합니다. 제품 의도 확인이나 범위 확장이 필요하면 충돌한 문서 경로·근거, 확인할 질문, 보류 이유와 실제 후속 task/Feature/issue 참조를 기록합니다. 없는 번호나 승인을 만들지 않습니다. 추적 항목 생성에 승인이 필요하면 사용자 확인 전 해결된 것으로 기록하지 않습니다. `NONE`의 근거에는 알려진 불일치가 없거나, 남은 불일치가 해당 후속 항목으로 추적되고 있음을 설명합니다. 코드나 OpenWiki에 맞추기 위해 미구현 PRD 요구를 삭제하지 않습니다.
|
|
55
|
+
|
|
54
56
|
> 모든 결정이 `NONE`이어도 영향 판정을 완료합니다. `NONE`은 사람이 관리하는 상위 문서를 검토했지만 변경할 필요가 없다는 뜻입니다. 생성형 OpenWiki 동기화는 별도로 판정합니다.
|
|
55
57
|
|
|
56
58
|
- **Schema**: 2
|