日本語からリファインメント+英語化の手間を減らして設計・実装までやらせるSKILL.md

SKILL.md

name	design-and-execute
description	Take a Japanese requirement, refine it to an English brief and plan the design doc, pause for approval, write the design doc to design_docs/, pause for approval, auto-derive an execution plan, pause for approval, and finally implement it. Triggers on: design-and-execute, /design-and-execute, 設計と実行, 設計してから実装, 日本語で要件, 設計書を作って実装.
user-invocable	true

Design-and-Execute

A single-invocation pipeline that strictly enforces a 4-phase sequence to absorb the user's manual workflow: Japanese requirement → 1. Plan Design Doc → [PAUSE] → 2. Write Design Doc →[PAUSE] → 3. Plan Implementation → [PAUSE] → 4. Execute Implementation.

🚨 CRITICAL FIXES FOR KNOWN ISSUES

To prevent previously observed failures, you MUST follow these absolute rules:

1. プランモードに入らないことがある (Sometimes skips planning): You must explicitly treat Phase 1 and Phase 3 as "Planning Mode". In these phases, you must ONLY output the plan text. Do NOT write files or code during these phases.
2. プランモードに入ってプランを立てたあとにその承認を私に求めない (Does not ask for approval after planning): At the end of Phase 1, Phase 2, and Phase 3, you MUST IMMEDIATELY STOP GENERATION and explicitly ask the user for approval. Do not auto-proceed to the next phase in the same response.
3. 設計ドキュメントの指定した箇所への書き出しが、実装等が完了した後に行われることがある (Writes design doc after implementation): Strict sequential execution is mandatory. You are FORBIDDEN from touching application code until the design document (design_docs/*.md) is completely written, reviewed, and approved in Phase 2.

---

The Job (4 Strict Phases)

Given a Japanese requirement as input, execute these four phases in order. You must wait for the user's input at every [MANDATORY PAUSE].

Phase 1 — Refine & Plan Design Document (Plan Mode 1)

1. Refine: Translate and restructure the Japanese requirement into a tight English engineering brief.
   • Preserve every constraint. Strip filler and meta-commentary. Do not invent requirements.
   • Structure: Goal:, Constraints:, In-scope:, Out-of-scope:, Open questions:.
   • If blocking open questions exist, call AskUserQuestion to resolve before proceeding.
2. Plan the Design Doc: Outline what design document(s) you will create under <project-root>/design_docs/ to satisfy the brief. Propose the filenames and structure.
3. [MANDATORY PAUSE 1]: Stop generation completely. Ask the user: "Do you approve this brief and the plan for the design document?"
   • DO NOT write the design document to a file yet.

---

Phase 2 — Write Design Document (Edit Mode 1)

Wait for Phase 1 approval before starting Phase 2.

1. Write the Doc: Create the design document(s) under <project-root>/design_docs/ based on the approved plan.
   • Determine <project-root> (detect with git rev-parse --show-toplevel or ask if ambiguous). Create design_docs/ if it does not exist.
   • Filename Convention (Mandatory): <NN>_<task-prefix>_<role-keyword>.md (e.g., 01_priority-field_overview.md, 02_priority-field_frontend.md). Lowercase, kebab-case, no Japanese characters.
   • Splitting Docs: For larger tasks, split by concern (one role per file). 01_..._overview.md must carry Context and Architecture and link to the rest.
   • Structure: Must include 8 sections: 1. # <Title>, 2. ## Context, 3. ## Architecture, 4. ## Files to Create (repo-rooted paths), 5. ## Files to Modify, 6. ## Implementation Steps (numbered, atomic), 7. ## Verification, 8. ## Key Design Decisions / Known Limitations (Optional).
   • Reuse-first scan (Mandatory): Search the project for existing helpers/components before specifying new code. Cite them in the doc with file paths and symbol names.
2. Sub-agent Review: Launch a general-purpose Agent (or use self-reflection) to critique the design doc for missing context, skipped reuse, and structural deviations. Require a structured response (Blocking issues: / Should fix: / Nits: / Looks good:). Edit the doc to resolve Blocking and Should fix items before proceeding.
3. [MANDATORY PAUSE 2]: Stop generation completely. Ask the user: "I have written the design document to design_docs/. Please review it. Do you approve, or should I make changes?"
   • DO NOT proceed to implementation planning. DO NOT modify any application files yet.

---

Phase 3 — Plan Implementation (Plan Mode 2)

Wait for Phase 2 approval before starting Phase 3.

1. Read the Source of Truth: Read the approved design document at <project-root>/design_docs/....
2. Derive Execution Prompt: Auto-derive an English execution prompt conceptually matching this template (do not ask the user for a second Japanese input):

   Implement the design specified at <absolute path to design_docs/...>.
   Source of truth: that file. Read it first.
   Work to do: every step in the doc's "Implementation Steps", in order.
   Files: those listed under "Files to Create" and "Files to Modify" — do not touch others.
   Reuse: prefer the existing helpers named in the design doc; do not reimplement them.
   Acceptance: every item in the doc's "Verification" section must pass.
   Do not expand scope or refactor adjacent code.
   

3. Output the Implementation Plan: Present a step-by-step plan of how you will implement the code, strictly following the "Implementation Steps" in the design doc.
4. [MANDATORY PAUSE 3]: Stop generation completely. Ask the user: "Do you approve this implementation plan?"
   • DO NOT touch application code or create the TODO file yet.

---

Phase 4 — Execute Implementation (Edit Mode 2)

Wait for Phase 3 approval before starting Phase 4.

Follow this execution protocol strictly:

4a. Create the task tracker first

Before touching code, create TODO_<short-keyword>.md at the project root.

• <short-keyword> should match the task prefix.
• Mirror the design doc's "Implementation Steps" as a markdown checklist.
• Include an initially empty ## Deferred section.
• Copy the ## Verification section from the design doc as a checklist.

4b. Work the steps one at a time, commit after each

For each unchecked step in the TODO file:

1. Implement exactly that step. Do not bundle multiple steps.
2. Tick the box in TODO_<short-keyword>.md (- [ ] → -[x]).
3. Stage the changed files + the TODO file.
4. Commit with a scoped message: <type>(<area>): <step summary> (e.g., feat(counter): add skeleton). Use whichever convention the repo already follows.
5. git push the commit.

4c. Capture deferrals

If a step is blocked or out-of-scope, add it to ## Deferred in the TODO file with a one-line reason. Do not silently drop it.

4d. Run verification

After all steps are ticked, run every item in the "Verification" checklist. Fix underlying issues if checks fail, rather than weakening the check. Commit the fixes.

4e. Sub-agent review of the implementation

When verification is green, launch a general-purpose Agent to review the diff vs. the design doc. Assess scope adherence, dead code, missing error handling, and commit cleanliness. Address "Blocking" / "Should fix" findings in new commits.

4f. Final report

Summarize what shipped (link the TODO file), explicitly list any deferred items, and report review outcomes. Stop and inform the user that execution is complete.

---

Output Contract

• Phase 2: <project-root>/design_docs/<NN>_<task-prefix>_<role-keyword>.md
• Phase 4: <project-root>/TODO_<short-keyword>.md
• Phase 4: Per-step commits pushed to the remote.
• No application files are written until Phase 4.

---

Guardrails Checklist

Before considering the skill invocation complete, verify:

• Did you explicitly pause and wait for user input at the end of Phases 1, 2, and 3?
• Was the design document fully written and approved BEFORE any implementation code was touched?
• Did you use the <NN>_<task-prefix>_<role-keyword>.md convention?
• Did you do one commit per step?
• Were deferred items recorded in the TODO file instead of silently dropped?