kotonoha 0.1.1 → 0.1.4
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/CHANGELOG.md +42 -0
- package/README.md +99 -20
- package/bin/kotonoha.js +81 -13
- package/package.json +7 -3
- package/skills/presentation-planner/SKILL.md +243 -0
- package/skills/presentation-planner/assets/design-templates/data-report.yaml +97 -0
- package/skills/presentation-planner/assets/design-templates/executive-proposal.yaml +92 -0
- package/skills/presentation-planner/assets/design-templates/technical-briefing.yaml +96 -0
- package/skills/presentation-planner/assets/scenario-templates/data-report.md +47 -0
- package/skills/presentation-planner/assets/scenario-templates/executive-decision.md +43 -0
- package/skills/presentation-planner/assets/scenario-templates/technical-briefing.md +45 -0
- package/skills/presentation-planner/references/customizing-design-templates.md +160 -0
- package/skills/presentation-planner/references/design-spec-schema.md +72 -0
- package/skills/presentation-planner/references/handoff-contract.md +49 -0
- package/skills/presentation-planner/references/responsibility-boundary.md +32 -0
- package/skills/presentation-planner/references/scenario-templates.md +55 -0
- package/skills/tech-writer/SKILL.md +108 -20
- package/skills/tech-writer/assets/templates/migration-plan.md +173 -0
- package/skills/tech-writer/assets/templates/operations-runbook.md +202 -0
- package/skills/tech-writer/assets/templates/requirements-definition.md +170 -0
- package/skills/tech-writer/assets/templates/rfi.md +113 -0
- package/skills/tech-writer/assets/templates/rfp.md +180 -0
- package/skills/tech-writer/assets/templates/security-design.md +167 -0
- package/skills/tech-writer/assets/templates/system-design.md +220 -0
- package/skills/tech-writer/assets/templates/technical-proposal.md +112 -0
- package/skills/tech-writer/assets/templates/test-plan.md +153 -0
- package/skills/tech-writer/references/doctypes/migration-plan.md +63 -0
- package/skills/tech-writer/references/doctypes/operations-runbook.md +63 -0
- package/skills/tech-writer/references/doctypes/requirements-definition.md +61 -0
- package/skills/tech-writer/references/doctypes/rfi.md +43 -0
- package/skills/tech-writer/references/doctypes/rfp.md +46 -0
- package/skills/tech-writer/references/doctypes/security-design.md +71 -0
- package/skills/tech-writer/references/doctypes/system-design.md +74 -0
- package/skills/tech-writer/references/doctypes/technical-proposal.md +49 -0
- package/skills/tech-writer/references/doctypes/test-plan.md +67 -0
- package/skills/tech-writer/references/style-constitution.md +7 -6
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# PPTX handoff contract
|
|
2
|
+
|
|
3
|
+
Use this structure for
|
|
4
|
+
`.presentation/<deck-slug>/pptx-handoff.md`.
|
|
5
|
+
|
|
6
|
+
## Inputs
|
|
7
|
+
|
|
8
|
+
- Brief: `<path>/presentation-brief.md`
|
|
9
|
+
- Scenario: `<path>/presentation-scenario.md`
|
|
10
|
+
- Slide outline: `<path>/slide-outline.md`
|
|
11
|
+
- Design specification: `<path>/design-spec.yaml`
|
|
12
|
+
- Source materials: `<paths>`
|
|
13
|
+
|
|
14
|
+
## Output
|
|
15
|
+
|
|
16
|
+
- PPTX path: `<path>/<filename>.pptx`
|
|
17
|
+
- Aspect ratio: `<16:9 / 4:3 / custom>`
|
|
18
|
+
- Expected slide count: `<count or range>`
|
|
19
|
+
|
|
20
|
+
## Rendering requirements
|
|
21
|
+
|
|
22
|
+
- Preserve slide order and assertion titles.
|
|
23
|
+
- Preserve the approved scenario stages and audience reasoning journey.
|
|
24
|
+
- Require every slide to map to at least one scenario stage; preserve
|
|
25
|
+
multi-stage mappings recorded with ` / ` in the outline.
|
|
26
|
+
- Treat evidence and citation fields as content requirements.
|
|
27
|
+
- Apply semantic design tokens from `design-spec.yaml`.
|
|
28
|
+
- Add speaker notes where specified.
|
|
29
|
+
- Add alt text or an equivalent description for informative visuals.
|
|
30
|
+
- Do not invent quantitative claims or citations.
|
|
31
|
+
|
|
32
|
+
## Required visual QA
|
|
33
|
+
|
|
34
|
+
- Render every slide to an image or thumbnail.
|
|
35
|
+
- Check clipping, overlap, off-canvas objects, font substitution, and
|
|
36
|
+
unreadable contrast.
|
|
37
|
+
- Check charts for legible labels, units, legends, and source notes.
|
|
38
|
+
- Check diagrams for readable flow direction and connector attachment.
|
|
39
|
+
- Report every deviation from the outline or design specification.
|
|
40
|
+
|
|
41
|
+
## Completion report
|
|
42
|
+
|
|
43
|
+
Return:
|
|
44
|
+
|
|
45
|
+
1. Output path and final slide count
|
|
46
|
+
2. Visual QA result
|
|
47
|
+
3. Missing or substituted assets/fonts
|
|
48
|
+
4. Deviations from the scenario, outline, or design and their reasons
|
|
49
|
+
5. Remaining manual-review items
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Responsibility boundary with the PPTX creation skill
|
|
2
|
+
|
|
3
|
+
`presentation-planner` and the host's PPTX skill are complementary.
|
|
4
|
+
|
|
5
|
+
| Concern | presentation-planner | PPTX creation skill |
|
|
6
|
+
|---|---:|---:|
|
|
7
|
+
| Audience, outcome, and decision | Owns | Consumes |
|
|
8
|
+
| Scenario and audience reasoning journey | Owns | Preserves |
|
|
9
|
+
| Storyline and slide sequence | Owns | Preserves |
|
|
10
|
+
| Assertion titles and evidence mapping | Owns | Renders |
|
|
11
|
+
| Design tokens and layout intent | Owns | Implements |
|
|
12
|
+
| `.pptx` binary creation and editing | Never | Owns |
|
|
13
|
+
| python-pptx/PptxGenJS/COM code | Never | Owns |
|
|
14
|
+
| Theme/layout extraction from an existing PPTX | Requests and consumes summary | Owns |
|
|
15
|
+
| Rendering and thumbnails | Never | Owns |
|
|
16
|
+
| Overlap, clipping, and font checks | Defines acceptance criteria | Executes |
|
|
17
|
+
| Speaker notes insertion | Specifies content | Implements |
|
|
18
|
+
|
|
19
|
+
## Conflict rule
|
|
20
|
+
|
|
21
|
+
If both skills could act, `presentation-planner` runs first and creates the
|
|
22
|
+
handoff package. The PPTX skill starts only after the planning artifacts are
|
|
23
|
+
complete. For a simple mechanical edit to an existing presentation where
|
|
24
|
+
the storyline and design are unchanged, skip `presentation-planner` and use
|
|
25
|
+
the PPTX skill directly.
|
|
26
|
+
|
|
27
|
+
## Failure rule
|
|
28
|
+
|
|
29
|
+
If the PPTX skill cannot implement a requested visual instruction, it must
|
|
30
|
+
report the constraint and proposed fallback. The planning skill may update
|
|
31
|
+
the design spec or slide outline, but it must not work around the constraint
|
|
32
|
+
by manipulating the PPTX binary itself.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Presentation scenario templates
|
|
2
|
+
|
|
3
|
+
A presentation scenario defines the audience's reasoning journey between the
|
|
4
|
+
brief and the slide-by-slide outline. It is not a script and does not repeat
|
|
5
|
+
all slide content. It records the assertions, evidence, transitions,
|
|
6
|
+
objections, and final action that make the deck persuasive and coherent.
|
|
7
|
+
|
|
8
|
+
## Artifact boundary
|
|
9
|
+
|
|
10
|
+
| Artifact | Question it answers |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `presentation-brief.md` | Who is the audience, and what outcome is required? |
|
|
13
|
+
| `presentation-scenario.md` | What reasoning journey moves them to that outcome? |
|
|
14
|
+
| `slide-outline.md` | Which slides deliver each assertion and piece of evidence? |
|
|
15
|
+
| `design-spec.yaml` | Which visual system expresses the content? |
|
|
16
|
+
| `pptx-handoff.md` | How must the PPTX skill generate and validate the deck? |
|
|
17
|
+
|
|
18
|
+
Do not use the scenario as a second slide outline. A scenario stage may span
|
|
19
|
+
several slides, or two stages may share one slide when the argument remains
|
|
20
|
+
clear.
|
|
21
|
+
|
|
22
|
+
## Choose a template
|
|
23
|
+
|
|
24
|
+
| Template | Use when | Avoid when |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| `executive-decision.md` | The audience must approve an option, investment, roadmap, or policy | The goal is purely educational |
|
|
27
|
+
| `technical-briefing.md` | The audience must understand or review architecture and technical behavior | The deck is primarily KPI analysis |
|
|
28
|
+
| `data-report.md` | Findings, trends, research, or experiments must support an action | Credible data is unavailable |
|
|
29
|
+
|
|
30
|
+
Copy the closest template to
|
|
31
|
+
`.presentation/<deck-slug>/presentation-scenario.md`, then remove stages that
|
|
32
|
+
do not advance the required outcome. Do not add stages or slides merely to
|
|
33
|
+
match the template.
|
|
34
|
+
|
|
35
|
+
If none fits, create `presentation-scenario.md` from the generic fallback in
|
|
36
|
+
`SKILL.md`, preserving the same stage, audience-question, assertion, evidence,
|
|
37
|
+
transition, and suggested-slide-range fields used by packaged templates.
|
|
38
|
+
|
|
39
|
+
## Adaptation rules
|
|
40
|
+
|
|
41
|
+
- Express each stage as an assertion the audience must accept.
|
|
42
|
+
- Record the audience question answered by each stage.
|
|
43
|
+
- Map factual claims to sources or mark them as assumptions.
|
|
44
|
+
- State the transition: why accepting one stage makes the next relevant.
|
|
45
|
+
- Include objections, uncertainty, and trade-offs before the final action.
|
|
46
|
+
- Keep the final decision or call to action singular and testable.
|
|
47
|
+
- Set suggested slide counts only as planning ranges, never quotas.
|
|
48
|
+
|
|
49
|
+
## Validation
|
|
50
|
+
|
|
51
|
+
- Reading only stage assertions reconstructs the argument.
|
|
52
|
+
- Every stage changes what the audience knows, believes, or is ready to do.
|
|
53
|
+
- Evidence strength matches the certainty of the assertion.
|
|
54
|
+
- The slide outline maps every slide to a scenario stage.
|
|
55
|
+
- No slide introduces a new conclusion absent from the approved scenario.
|
|
@@ -3,15 +3,25 @@ name: tech-writer
|
|
|
3
3
|
description: >-
|
|
4
4
|
Helps structure and polish technical documents: README, design docs/ADRs,
|
|
5
5
|
API reference, PR descriptions/commit messages/issue reports, release
|
|
6
|
-
notes/CHANGELOG, user manuals/how-to guides, code comments/docstrings,
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
6
|
+
notes/CHANGELOG, user manuals/how-to guides, code comments/docstrings,
|
|
7
|
+
requirements definitions, system designs, test plans, operations runbooks,
|
|
8
|
+
migration plans, security designs/threat models, technical proposals,
|
|
9
|
+
RFI/RFP procurement documents, and Qiita/Zenn articles. Use for requests
|
|
10
|
+
like "write a README", "draft a design doc", "define system requirements",
|
|
11
|
+
"write a system design", "create a test plan", "write an operations
|
|
12
|
+
runbook", "plan a migration", "create a threat model", "write a technical
|
|
13
|
+
proposal", "draft an RFI", "create an RFP", "write this PR description",
|
|
14
|
+
"clean up my commit
|
|
15
|
+
message", "make this how-to guide clearer", "write API docs", "summarize
|
|
16
|
+
the release notes", "write a Zenn article", "write this up for Qiita", as
|
|
17
|
+
well as
|
|
11
18
|
Japanese-language equivalents (「READMEを書いて」「設計ドキュメントを作って」
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
19
|
+
「要件定義書を作って」「システム設計書を書いて」「テスト計画書を作って」
|
|
20
|
+
「運用設計書を書いて」「移行計画を作って」「脅威モデルを作って」
|
|
21
|
+
「技術提案書を書いて」「RFIを作って」「RFPを作って」「PRの説明文を書いて」
|
|
22
|
+
「コミットメッセージを整えて」「手順書を分かりやすくして」
|
|
23
|
+
「APIドキュメントを整備して」「リリースノートをまとめて」
|
|
24
|
+
「Zennの記事を書いて」「Qiitaに投稿する記事を書いて」). Especially useful when
|
|
15
25
|
the request is a bare goal without enough context to start (e.g. "I want
|
|
16
26
|
to write a README" / "○○を書きたい"), since this skill drives a one
|
|
17
27
|
question-at-a-time intake before writing. Supports both Japanese and
|
|
@@ -31,7 +41,10 @@ argument-hint: "[write|review|score] [doctype] <target file or request>"
|
|
|
31
41
|
Structures technical documents so readers reach the information they need
|
|
32
42
|
with the shortest path. Covers README, design docs/ADRs, API reference, PR
|
|
33
43
|
descriptions/commit messages/issue reports, release notes/CHANGELOG, user
|
|
34
|
-
manuals/how-to guides, code comments/docstrings,
|
|
44
|
+
manuals/how-to guides, code comments/docstrings, requirements definitions,
|
|
45
|
+
system designs, test plans, operations runbooks, migration plans, security
|
|
46
|
+
designs/threat models, technical proposals, RFI/RFP procurement documents,
|
|
47
|
+
and Qiita/Zenn articles.
|
|
35
48
|
|
|
36
49
|
Default format: Markdown for every doctype in this skill, except a git
|
|
37
50
|
commit message body (plain text by convention — light "-" bullets are
|
|
@@ -62,9 +75,12 @@ first, then hand Japanese prose to natural-japanese for polish.
|
|
|
62
75
|
Infer the mode from the argument or the request:
|
|
63
76
|
|
|
64
77
|
- `write` (default): new document, or restructuring a draft. Runs the full
|
|
65
|
-
§1–§
|
|
78
|
+
§1–§5 workflow, starting with the intake loop in §1 and ending only after
|
|
79
|
+
the rubber-duck review loop has no remaining actionable findings. If an
|
|
80
|
+
independent review cannot run or cannot converge, returns the explicit
|
|
81
|
+
review status required by §5 instead of claiming a clean review.
|
|
66
82
|
- `review`: structural review of an existing document. Does not rewrite;
|
|
67
|
-
reports the gap against the doctype checklist (§
|
|
83
|
+
reports the gap against the doctype checklist (§6).
|
|
68
84
|
- `score`: structure-only quick diagnostic. Runs
|
|
69
85
|
`scripts/lint.py --json <file>` and summarizes the findings (no rewrite).
|
|
70
86
|
|
|
@@ -87,7 +103,13 @@ hand the user a checklist to fill in. Instead:
|
|
|
87
103
|
past this doctype without knowing which one applies. Similarly, a bare
|
|
88
104
|
"write a tech blog post" request doesn't by itself say Qiita, Zenn, or
|
|
89
105
|
neither — ask which platform (or "no platform, just a plain document")
|
|
90
|
-
as part of this same first question.
|
|
106
|
+
as part of this same first question. For a "technical proposal", ask
|
|
107
|
+
whether it is an internal approval proposal or a supplier response to an
|
|
108
|
+
RFP; only the internal approval proposal maps to `technical-proposal`.
|
|
109
|
+
For a supplier response, structure the document against the supplied
|
|
110
|
+
RFP's requirement IDs, requested proposal contents, pricing format, and
|
|
111
|
+
contract deviations, then apply the general principles in
|
|
112
|
+
`references/style-constitution.md`.
|
|
91
113
|
2. Open the matching reference file and note its target reader and any
|
|
92
114
|
"settle before writing" items. Combined with the general musts below,
|
|
93
115
|
this is your information checklist — but never show it to the user as a
|
|
@@ -101,7 +123,12 @@ hand the user a checklist to fill in. Instead:
|
|
|
101
123
|
doctype (and subtype, for `pr-commit`), and (d) any doctype-specific
|
|
102
124
|
musts (e.g. the decision and alternatives for a design doc, the
|
|
103
125
|
prior-knowledge floor for a user manual, breaking-change status for
|
|
104
|
-
release notes, the related issue for a PR description or bug report
|
|
126
|
+
release notes, the related issue for a PR description or bug report,
|
|
127
|
+
measurable acceptance conditions for a requirements definition, the
|
|
128
|
+
approved requirements baseline for a system design, exit criteria for a
|
|
129
|
+
test plan, RTO/RPO for an operations runbook, rollback conditions for a
|
|
130
|
+
migration plan, assets and trust boundaries for a threat model, market
|
|
131
|
+
unknowns for an RFI, or evaluation rules for an RFP).
|
|
105
132
|
5. **A "don't know" / "not applicable" / "no ticket for this" answer
|
|
106
133
|
satisfies a must — it is not a reason to keep asking.** Ask that must
|
|
107
134
|
at most once; if the answer is a non-answer, record it as a stated
|
|
@@ -110,7 +137,7 @@ hand the user a checklist to fill in. Instead:
|
|
|
110
137
|
one-line note) and move on.
|
|
111
138
|
6. **Once complete, do not ask the user to compose anything.** Synthesize
|
|
112
139
|
the gathered answers into the best possible generation approach yourself
|
|
113
|
-
and immediately continue into §2–§
|
|
140
|
+
and immediately continue into §2–§5 in the same turn to produce the
|
|
114
141
|
document. Skip further confirmation unless the doctype is release-facing
|
|
115
142
|
and consequential (e.g. a public release note with breaking changes) or
|
|
116
143
|
the user explicitly asked to see a plan first.
|
|
@@ -127,6 +154,15 @@ hand the user a checklist to fill in. Instead:
|
|
|
127
154
|
| Release notes / CHANGELOG | release-notes | `references/doctypes/release-notes.md` |
|
|
128
155
|
| User manual / how-to guide / tutorial | user-manual | `references/doctypes/user-manual.md` |
|
|
129
156
|
| Code comments / docstrings | code-comments | `references/doctypes/code-comments.md` |
|
|
157
|
+
| Requirements definition / 要件定義書 | requirements-definition | `references/doctypes/requirements-definition.md` |
|
|
158
|
+
| System design / システム設計書 | system-design | `references/doctypes/system-design.md` |
|
|
159
|
+
| Test plan / テスト計画書 | test-plan | `references/doctypes/test-plan.md` |
|
|
160
|
+
| Operations design / Runbook / 運用設計書 | operations-runbook | `references/doctypes/operations-runbook.md` |
|
|
161
|
+
| Migration plan / 移行計画書 | migration-plan | `references/doctypes/migration-plan.md` |
|
|
162
|
+
| Security design / Threat model / セキュリティ設計書 | security-design | `references/doctypes/security-design.md` |
|
|
163
|
+
| Internal technical proposal | technical-proposal | `references/doctypes/technical-proposal.md` |
|
|
164
|
+
| Request for information / RFI | rfi | `references/doctypes/rfi.md` |
|
|
165
|
+
| Request for proposal / RFP | rfp | `references/doctypes/rfp.md` |
|
|
130
166
|
| Zenn article | zenn | `references/doctypes/zenn.md` |
|
|
131
167
|
| Qiita article | qiita | `references/doctypes/qiita.md` |
|
|
132
168
|
|
|
@@ -137,9 +173,12 @@ one-question-at-a-time intake for reader and outcome.
|
|
|
137
173
|
## 2. Outline first for long documents
|
|
138
174
|
|
|
139
175
|
For documents likely to run long — design docs/ADRs, user manuals with
|
|
140
|
-
multiple steps, API references covering several endpoints,
|
|
141
|
-
|
|
142
|
-
|
|
176
|
+
multiple steps, API references covering several endpoints, requirements
|
|
177
|
+
definitions, system designs, test plans, operations runbooks, migration
|
|
178
|
+
plans, security designs, technical proposals, RFI/RFP documents, or anything
|
|
179
|
+
the user calls
|
|
180
|
+
"long"/"detailed"/"comprehensive" — draft a table of contents (heading
|
|
181
|
+
outline) before writing any body prose.
|
|
143
182
|
|
|
144
183
|
1. Build the heading outline from the reader and outcome gathered in §1 and
|
|
145
184
|
the doctype's recommended skeleton (in its reference file).
|
|
@@ -165,7 +204,9 @@ document and needs the outline step below.
|
|
|
165
204
|
## 3. Write — under the structure constitution
|
|
166
205
|
|
|
167
206
|
For living, multi-section documents (README, design doc, API reference,
|
|
168
|
-
release notes, user manual,
|
|
207
|
+
release notes, user manual, requirements definition, system design, test
|
|
208
|
+
plan, operations runbook, migration plan, security design, technical
|
|
209
|
+
proposal, RFI/RFP, Zenn/Qiita article), write under the 8 rules
|
|
169
210
|
in `references/style-constitution.md`. Summary: state "what this is" and
|
|
170
211
|
"the outcome for the reader" in the first three lines; make headings
|
|
171
212
|
labels that preview content (not "Overview", but "Overview of what");
|
|
@@ -221,11 +262,58 @@ step 2 as the primary check for those.
|
|
|
221
262
|
4. **Reader-goal recheck**: confirm the "what the reader can do after
|
|
222
263
|
reading" outcome from §1 is actually achievable from this document alone.
|
|
223
264
|
|
|
224
|
-
## 5.
|
|
265
|
+
## 5. Rubber-duck review loop — write mode only
|
|
266
|
+
|
|
267
|
+
After the structural review in §4, use the host's subagent mechanism to
|
|
268
|
+
launch an independent reviewer in the `rubber-duck` role to challenge the
|
|
269
|
+
completed document for meaningful problems that the authoring pass may have
|
|
270
|
+
missed. Prefer a registered `rubber-duck` agent when the host provides one;
|
|
271
|
+
otherwise use an independent general-purpose or critic-style subagent with
|
|
272
|
+
the same review prompt. Treat the reviewer as unavailable only when the host
|
|
273
|
+
has no independent subagent mechanism. Do not substitute the author's own
|
|
274
|
+
self-review: independence is the point of this pass. This loop is mandatory
|
|
275
|
+
for `write` mode; do not run it for `review` or `score` mode.
|
|
276
|
+
|
|
277
|
+
1. **Start the review with full context**: give the reviewer the target file,
|
|
278
|
+
doctype, intended reader, one-sentence reader outcome from §1, and any
|
|
279
|
+
explicit constraints or assumptions. Ask it to report concrete,
|
|
280
|
+
actionable problems in correctness, logic, missing information, reader
|
|
281
|
+
flow, examples, and stated limitations — not cosmetic preferences.
|
|
282
|
+
2. **Resolve every valid finding**: edit the document rather than merely
|
|
283
|
+
listing proposed fixes. If a finding conflicts with a stated requirement
|
|
284
|
+
or is factually inapplicable, record a one-line reason for declining it.
|
|
285
|
+
3. **Re-run the relevant checks after each edit round**: repeat the doctype
|
|
286
|
+
checklist and structural lint from §4 before asking for another
|
|
287
|
+
rubber-duck review. A fix must not introduce a new structural defect.
|
|
288
|
+
4. **Review again with the prior decisions**: reuse the same reviewer context
|
|
289
|
+
when supported. Otherwise, include the previous findings, applied fixes,
|
|
290
|
+
and declined findings with their reasons in every new review prompt. Ask
|
|
291
|
+
specifically for unresolved or newly introduced actionable findings.
|
|
292
|
+
5. **Use a bounded convergence rule**: allow at most five rubber-duck rounds
|
|
293
|
+
for a living, multi-section document. For an atomic artifact, run one
|
|
294
|
+
round and finish immediately if it is clean; only continue after an
|
|
295
|
+
actionable finding, with a maximum of three rounds. A round is clean only
|
|
296
|
+
when no unaddressed actionable correctness, logic, completeness,
|
|
297
|
+
reader-flow, example, or limitation findings remain. A finding declined
|
|
298
|
+
with a recorded requirement-based or factual reason is a resolved
|
|
299
|
+
exception rather than an open finding. If another round runs, supply that
|
|
300
|
+
exception back to the reviewer under step 4. Purely cosmetic preferences
|
|
301
|
+
are not actionable.
|
|
302
|
+
6. **Report non-clean outcomes precisely**: if the host has no independent
|
|
303
|
+
reviewer, label the result `review not performed` and do not claim the
|
|
304
|
+
rubber-duck pass completed. If the round limit is reached with
|
|
305
|
+
unaddressed actionable findings, or findings oscillate between
|
|
306
|
+
contradictory requirements, label it `review did not converge` and
|
|
307
|
+
include the latest unresolved findings and fixes already attempted.
|
|
308
|
+
|
|
309
|
+
## 6. Doctype checklist summary
|
|
225
310
|
|
|
226
311
|
See each reference file for detail. The items below are for living,
|
|
227
312
|
multi-section documents (README, design doc, API reference, release notes,
|
|
228
|
-
user manual,
|
|
313
|
+
user manual, requirements definition, system design, test plan, operations
|
|
314
|
+
runbook, migration plan, security design, technical proposal, RFI/RFP,
|
|
315
|
+
Zenn/Qiita article). Atomic
|
|
316
|
+
artifacts (commit message, PR
|
|
229
317
|
description, issue report, code comment/docstring, a single appended
|
|
230
318
|
release-notes entry) are already covered by their own doctype checklist
|
|
231
319
|
via step 2 in §4 — these common items don't add extra requirements on top
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# <システム・データ名> 移行計画書
|
|
2
|
+
|
|
3
|
+
<何をどこからどこへ、どの停止許容時間と品質基準で安全に移行するかを3文以内で要約する。>
|
|
4
|
+
|
|
5
|
+
- 文書版: <例: 1.0>
|
|
6
|
+
- 作成日: <YYYY-MM-DD>
|
|
7
|
+
- 最終更新日: <YYYY-MM-DD>
|
|
8
|
+
- 移行責任者: <氏名・チーム>
|
|
9
|
+
- Go / No-Go判断者: <氏名・会議体>
|
|
10
|
+
- ステータス: Draft / In Review / Approved
|
|
11
|
+
- 本番移行予定: <YYYY-MM-DD HH:mm–HH:mm TZ>
|
|
12
|
+
- 関連要件・設計: <文書名・版・URL>
|
|
13
|
+
|
|
14
|
+
## この移行計画で合意する事項
|
|
15
|
+
|
|
16
|
+
- 移行対象: <データ、利用者、機能、外部接続>
|
|
17
|
+
- 移行方式: <一括、段階、並行稼働など>
|
|
18
|
+
- 許容停止時間と品質基準: <値>
|
|
19
|
+
- 承認を求める事項: <日程、体制、判定、ロールバック>
|
|
20
|
+
|
|
21
|
+
## 現行と移行後の状態
|
|
22
|
+
|
|
23
|
+
| 項目 | 現行 | 移行後 | 主な変更 | 利用者への影響 |
|
|
24
|
+
|---|---|---|---|---|
|
|
25
|
+
| システム | <現行> | <移行先> | <変更> | <影響> |
|
|
26
|
+
| データ | <形式・量> | <形式・量> | <変換> | <影響> |
|
|
27
|
+
| 業務 | <手順> | <手順> | <変更> | <教育・周知> |
|
|
28
|
+
|
|
29
|
+
## 対象範囲と対象外
|
|
30
|
+
|
|
31
|
+
### 対象範囲
|
|
32
|
+
|
|
33
|
+
- <移行するデータ・設定・利用者・接続先>
|
|
34
|
+
|
|
35
|
+
### 対象外
|
|
36
|
+
|
|
37
|
+
- <廃止しないもの・後続フェーズへ送るもの>
|
|
38
|
+
|
|
39
|
+
## 前提条件と制約
|
|
40
|
+
|
|
41
|
+
| ID | 条件・制約 | 確認方法 | 期限 | 所有者 |
|
|
42
|
+
|---|---|---|---|---|
|
|
43
|
+
| MIG-CON-001 | <停止時間・契約・技術制約> | <確認> | <期限> | <担当> |
|
|
44
|
+
|
|
45
|
+
## 移行対象の棚卸し
|
|
46
|
+
|
|
47
|
+
| 対象ID | 対象 | 移行元 | 移行先 | 件数・容量 | 所有者 | 依存関係 | 移行要否 |
|
|
48
|
+
|---|---|---|---|---:|---|---|---|
|
|
49
|
+
| MIG-001 | <データ・設定> | <場所> | <場所> | <値> | <担当> | <依存先> | Yes / No |
|
|
50
|
+
|
|
51
|
+
## データマッピングと変換
|
|
52
|
+
|
|
53
|
+
| 移行元項目 | 移行先項目 | 変換ルール | 必須・既定値 | 検証ルール | エラー時の扱い |
|
|
54
|
+
|---|---|---|---|---|---|
|
|
55
|
+
| <項目> | <項目> | <変換> | <条件> | <型・範囲・参照整合性> | <除外・補正・中止> |
|
|
56
|
+
|
|
57
|
+
## 移行方式と移行単位
|
|
58
|
+
|
|
59
|
+
- 方式: 一括 / 段階 / 並行稼働 / Blue-Green / <その他>
|
|
60
|
+
- 選定理由: <停止時間、整合性、ロールバックとの関係>
|
|
61
|
+
- 差分同期: <CDC、二重書き、再実行など>
|
|
62
|
+
- 冪等性: <再実行しても重複・欠損しない仕組み>
|
|
63
|
+
|
|
64
|
+
| Wave | 対象 | 実施日時 | 完了条件 | 次Waveへの判定 |
|
|
65
|
+
|---|---|---|---|---|
|
|
66
|
+
| 1 | <対象> | <日時> | <条件> | <条件> |
|
|
67
|
+
|
|
68
|
+
## 体制と役割
|
|
69
|
+
|
|
70
|
+
| 役割 | 担当 | 責任 | 当日の連絡方法 | 代行者 |
|
|
71
|
+
|---|---|---|---|---|
|
|
72
|
+
| 移行指揮 | <担当> | Go / No-Go、進行 | <方法> | <担当> |
|
|
73
|
+
| データ移行 | <担当> | 抽出・変換・投入 | <方法> | <担当> |
|
|
74
|
+
| 業務確認 | <担当> | 業務受入 | <方法> | <担当> |
|
|
75
|
+
| 運用・監視 | <担当> | 監視・障害対応 | <方法> | <担当> |
|
|
76
|
+
|
|
77
|
+
## リハーサル計画
|
|
78
|
+
|
|
79
|
+
| 回 | 目的 | 対象・データ量 | 実施日 | 目標時間 | 合格条件 | 改善事項 |
|
|
80
|
+
|---|---|---|---|---:|---|---|
|
|
81
|
+
| 1 | <手順・性能・復旧の検証> | <範囲> | <日付> | <時間> | <条件> | <記録> |
|
|
82
|
+
|
|
83
|
+
## 移行開始条件
|
|
84
|
+
|
|
85
|
+
- <リハーサルが合格している>
|
|
86
|
+
- <対象版が承認され、変更凍結されている>
|
|
87
|
+
- <バックアップとリストア試験が完了している>
|
|
88
|
+
- <監視、連絡網、ロールバック環境が準備されている>
|
|
89
|
+
- <利用者通知と業務側の準備が完了している>
|
|
90
|
+
|
|
91
|
+
## 本番移行タイムライン
|
|
92
|
+
|
|
93
|
+
| 時刻 | 手順ID | 作業 | 実行者 | 想定時間 | 完了条件 | 証跡 |
|
|
94
|
+
|---|---|---|---|---:|---|---|
|
|
95
|
+
| <HH:mm> | STEP-001 | <作業> | <担当> | <分> | <確認可能な条件> | <ログ・画面> |
|
|
96
|
+
|
|
97
|
+
## 検証と照合
|
|
98
|
+
|
|
99
|
+
| 検証ID | 対象 | 検証方法 | 移行前値 | 移行後値 | 許容差 | 判定者 |
|
|
100
|
+
|---|---|---|---:|---:|---:|---|
|
|
101
|
+
| VAL-001 | 件数 | <SQL・レポート> | <値> | <値> | 0 | <担当> |
|
|
102
|
+
| VAL-002 | 金額・集計 | <照合方法> | <値> | <値> | <値> | <担当> |
|
|
103
|
+
| VAL-003 | 参照整合性 | <孤立・重複・外部キー検査> | <値> | <値> | 0 | <担当> |
|
|
104
|
+
| VAL-004 | 業務シナリオ | <操作> | <期待> | <実結果> | なし | <担当> |
|
|
105
|
+
|
|
106
|
+
## Go / No-Go判定
|
|
107
|
+
|
|
108
|
+
| 判定時点 | Go条件 | No-Go条件 | 必要な証跡 | 判断者 |
|
|
109
|
+
|---|---|---|---|---|
|
|
110
|
+
| 移行開始前 | <条件> | <条件> | <チェックリスト> | <担当> |
|
|
111
|
+
| 切替前 | <条件> | <条件> | <移行・照合結果> | <担当> |
|
|
112
|
+
| サービス再開前 | <条件> | <条件> | <業務確認・監視> | <担当> |
|
|
113
|
+
|
|
114
|
+
## ロールバック計画
|
|
115
|
+
|
|
116
|
+
- ロールバック可能期限: <時刻・条件>
|
|
117
|
+
- ロールバック判断条件: <時間超過、欠損、重大障害など>
|
|
118
|
+
- 判断者: <役割>
|
|
119
|
+
- データ整合性方針: <移行後更新の扱い>
|
|
120
|
+
|
|
121
|
+
| 手順 | 作業 | 実行者 | 想定時間 | 完了条件 |
|
|
122
|
+
|---:|---|---|---:|---|
|
|
123
|
+
| 1 | <新環境への書き込みを停止する> | <担当> | <分> | <条件> |
|
|
124
|
+
| 2 | <切替後に新環境へ書き込まれた差分を退避し、再適用・補償対象を確定する> | <担当> | <分> | <差分が固定され証跡がある> |
|
|
125
|
+
| 3 | <旧環境を復旧し、必要な差分を再適用または補償する> | <担当> | <分> | <整合性基準を満たす> |
|
|
126
|
+
| 4 | <データと業務を確認して旧環境を再開する> | <担当> | <分> | <再開条件を満たす> |
|
|
127
|
+
|
|
128
|
+
## 業務継続と利用者コミュニケーション
|
|
129
|
+
|
|
130
|
+
| 対象 | 通知内容 | 通知時期 | 手段 | 担当 |
|
|
131
|
+
|---|---|---|---|---|
|
|
132
|
+
| 利用者 | <停止・変更・再開> | <時期> | <メール・画面> | <担当> |
|
|
133
|
+
| 問い合わせ窓口 | <FAQ・既知問題> | <時期> | <手段> | <担当> |
|
|
134
|
+
| 経営・顧客 | <進捗・障害> | <条件> | <手段> | <担当> |
|
|
135
|
+
|
|
136
|
+
- 停止中の代替業務: <手作業・受付停止など>
|
|
137
|
+
- 再開後の問い合わせ増加対応: <増員・期間>
|
|
138
|
+
|
|
139
|
+
## セキュリティと監査
|
|
140
|
+
|
|
141
|
+
- 移行データの暗号化: <転送時・保存時>
|
|
142
|
+
- 一時ファイル: <保管場所・アクセス・削除期限>
|
|
143
|
+
- 特権アクセス: <申請・有効期限・監査>
|
|
144
|
+
- 個人情報・機密情報: <マスキング・取扱い>
|
|
145
|
+
- 操作証跡: <記録内容・保存期間>
|
|
146
|
+
|
|
147
|
+
## 移行後の安定化
|
|
148
|
+
|
|
149
|
+
| 期間 | 監視強化項目 | 判定基準 | 担当 | 通常運用への移行条件 |
|
|
150
|
+
|---|---|---|---|---|
|
|
151
|
+
| <期間> | <エラー率・照合・問い合わせ> | <閾値> | <担当> | <条件> |
|
|
152
|
+
|
|
153
|
+
- 旧環境の扱い: <参照専用、保持期間、廃止日>
|
|
154
|
+
- 一時データ・権限の削除: <期限・証跡>
|
|
155
|
+
- 未移行・エラーデータの処理: <方法・期限>
|
|
156
|
+
|
|
157
|
+
## リスクと未解決事項
|
|
158
|
+
|
|
159
|
+
| ID | 内容 | 影響 | 発生可能性 | 対策・期限 | 所有者 | ステータス |
|
|
160
|
+
|---|---|---|---|---|---|---|
|
|
161
|
+
| MIG-RSK-001 | <内容> | High / Medium / Low | High / Medium / Low | <対策> | <担当> | Open |
|
|
162
|
+
|
|
163
|
+
## 承認記録
|
|
164
|
+
|
|
165
|
+
| 版 | 承認日 | 承認者 | 判断 | 条件・コメント |
|
|
166
|
+
|---|---|---|---|---|
|
|
167
|
+
| <版> | <YYYY-MM-DD> | <氏名・会議体> | Approved / Rejected / Deferred | <条件> |
|
|
168
|
+
|
|
169
|
+
## 変更履歴
|
|
170
|
+
|
|
171
|
+
| 版 | 日付 | 変更内容 | 変更理由 | 作成者 |
|
|
172
|
+
|---|---|---|---|---|
|
|
173
|
+
| 0.1 | <YYYY-MM-DD> | 初版 | <理由> | <氏名> |
|