RsDT (Requirements, Specs, Design & Tasks) Instructions

Instructions for AI coding assistants using RsDT for specification-driven development.

IMPORTANT: All files generated by this skill (requirement-spec.md, design.md, tasks.md, ADRs, Design Docs) MUST be written in Japanese unless explicitly requested otherwise by the user.

TL;DR Quick Checklist

• Review existing work: Related codebase, existing features under RsDT/
• Decide <feature_name>: kebab-case, verb-led (add-, fix-, update-, refactor-)
• Deepen understanding: Codebase investigation, websearch, context7 MCP server, user questions
• Generate 3 files: requirement-spec.md, design.md, tasks.md (all in Japanese)
• Review drafts: Call rsdt-spec-reviewer sub-agent to verify compliance
• Implementation: Follow tasks.md order and check off upon completion

Workflow Overview

Stage 1: Draft - Requirements and Design Specification

Trigger Examples:

• "I want to add 〇〇 feature"
• "Fix this bug"
• "Create a refactoring plan"

Process:

1. Context Gathering

   • Read and understand related codebase
   • Check existing features under RsDT/ for duplicates or conflicts
   • If using external tools/libraries, check latest documentation via context7 MCP server
   • Use websearch for latest information as needed

2. Requirements Clarification

   • Assume user input may be memo-level quality
   • Identify unclear or ambiguous points
   • Read related code before asking questions to enable discussion
   • Use AskUserQuestion tool to clarify requirements

3. Feature Name Decision

   • kebab-case, verb-led naming
   • Examples: add-user-authentication, fix-login-bug, refactor-api-client
   • Create directory: RsDT/<feature_name>/

4. Generate 3 Files (in Japanese)

   • requirement-spec.md: Requirements and specifications
   • design.md: Design (as needed)
   • tasks.md: Task breakdown

5. Review Drafts (MANDATORY)

   • Call rsdt-spec-reviewer sub-agent using Task tool
   • Verify compliance with Design Philosophy and Important Reminders
   • Address any feedback before proceeding to Stage 2

Stage 2: Implementation - Build

Follow tasks while tracking with TodoWrite tool:

1. Read requirement-spec.md - Understand what to build
2. Read design.md - Understand how to build
3. Read tasks.md - Check implementation steps
4. Implement tasks sequentially - Follow tasks.md order
5. Confirm completion - Verify all tasks in tasks.md are finished
6. Update checklist - Mark all tasks as - [x] after completion

Stage 3: Archive - Post-Completion Cleanup

After implementation completion, organize as follows:

1. Delete tasks.md

   • Completed task list is no longer needed

2. Create ADRs (if needed)

   • Only if project manages ADRs (Architecture Decision Records)
   • Create individual ADRs for each architecture decision made
   • Check project's ADR policy and match existing format and file structure
   • Review existing ADRs to confirm naming conventions and location

3. Create Design Doc (if needed)

   • Only if content is worth keeping as specification documentation
   • Summarize requirements and design from requirement-spec.md and design.md
   • Place in appropriate project location (e.g., docs/design/, docs/specs/)

4. Delete Working Files

   • Delete requirement-spec.md
   • Delete design.md
   • Finally delete entire RsDT/<feature_name>/ directory

Directory Structure

RsDT/
└── <feature_name>/          # Work in progress (delete after completion)
    ├── requirement-spec.md  # Requirements and specs (Japanese)
    ├── design.md           # Design (optional, Japanese)
    └── tasks.md            # Task breakdown (Japanese)

Note: Directories under RsDT are temporary working directories. After implementation completion, create ADRs or Design Docs as needed, then delete the working directory.

File Format Guide

requirement-spec.md

IMPORTANT: Write this file in Japanese.

Include the following sections:

# <Feature Name>

## 背景・目的

[Why this feature is needed, what problem it solves]

## スコープ

### 実装すること
- [List of changes]
- [Mark BREAKING CHANGE with **BREAKING** if applicable]

### 実装しないこと
- [Explicitly list what's out of scope]

## 要件・仕様

### [Requirement Category] - ADDED/MODIFIED/REMOVED

#### 要件: [Requirement Name]

[Requirement description]

##### Scenario: [Scenario Name]
- **GIVEN** [Preconditions]
- **WHEN** [Actions/Events]
- **THEN** [Expected Results]

Or

##### Scenario: [Scenario Name]
- **Arrange** [Setup preconditions]
- **Act** [Execute actions]
- **Assert** [Verify results]

## 制約条件

- [Technical constraints]
- [Performance requirements]
- [Security requirements]
- [Other constraints]

Key Points:

• Each requirement must have at least one scenario
• Scenarios must use Given-When-Then or Arrange-Act-Assert format
• Explicitly mark whether requirement is ADDED, MODIFIED, or REMOVED

design.md

IMPORTANT: Write this file in Japanese.

Include as needed (not all sections are mandatory):

# <Feature Name> 設計

## 設計選択肢の検討

**Note: 複数の選択肢が存在する設計判断がある場合のみ記述。単純な要件で選択肢がほぼない場合は省略可。**

### [設計判断項目名]

| 選択肢 | 概要 | メリット | デメリット |
|--------|------|----------|------------|
| A: [選択肢A名] | [簡潔な説明] | [利点] | [欠点] |
| B: [選択肢B名] | [簡潔な説明] | [利点] | [欠点] |
| C: [選択肢C名] | [簡潔な説明] | [利点] | [欠点] |

**採用**: [選択肢X]
**理由**: [なぜこの選択肢を選んだか1-2文で簡潔に]

## Refactoring Analysis (REQUIRED)

### Existing Code Modification/Deletion Review

| Target | File:Line | Current State | Proposal | Reason |
|--------|-----------|---------------|----------|--------|
| [Function/Class name] | `file.ts:42` | [Current impl] | Delete/Modify/Merge | [Reason] |

### Deletion Targets
- [ ] `function_name` in `file.ts:XX` - [Reason for deletion]

### Modification Targets (including breaking changes)
- [ ] `function_name` in `file.ts:XX` - [Change details and reason]

### Consolidation Targets
- [ ] `func_a` + `func_b` → `new_func` - [Reason for consolidation]

### Justification for New Additions

**Only fill this section if new code is truly necessary**

| New Item | Reason Required | Why Existing Code Cannot Be Used |
|----------|-----------------|----------------------------------|
| [Function/Class name] | [Reason] | [Why existing code is insufficient] |

### Code Volume Estimate

- Lines to delete: XX
- Lines to modify: XX
- Lines to add: XX
- **Net change: ±XX lines** (Goal: minimize net increase)

## 全体構成

[System architecture diagram/explanation]

## コンポーネント設計

### [Component Name]
- 責務: [Component's responsibilities]
- インターフェース: [Public API]
- 依存関係: [Relationships with other components]

## データベース設計

### テーブル: [Table Name]
- カラム定義
- インデックス
- 制約

## API設計

### [Endpoint Name]
- メソッド: GET/POST/PUT/DELETE
- パス: /api/...
- リクエスト: [Parameters]
- レスポンス: [Return values]

## UI設計

[Screen transitions, component composition, etc.]

## 外部連携設計

[External API, library usage]

## セキュリティ設計

[Authentication, authorization, data protection, etc.]

## テスト設計

### [Test Type]

#### Test: [Test Name]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- **Given/Arrange**: [Preconditions]
- **When/Act**: [Execution]
- **Then/Assert**: [Verification]

Key Points:

• Tests must correspond to scenarios in requirement-spec.md
• Use the same Given-When-Then or Arrange-Act-Assert format for tests

tasks.md

IMPORTANT: Write this file in Japanese.

IMPORTANT: Tasks MUST be structured for TDD (Test-Driven Development). Each task should include writing the test first, then the implementation.

# <Feature Name> タスク

## Phase 1: [Phase Name]

### Task 1.1: [タスク名]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- [ ] テスト作成: [テスト内容の説明]
- [ ] テスト実行 → Red確認
- [ ] 実装: [実装内容の説明]
- [ ] テスト実行 → Green確認
- [ ] リファクタリング（必要な場合）
- [ ] Playwright MCP serverで動作確認（フロントエンド実装の場合）

### Task 1.2: [タスク名]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- [ ] テスト作成: [テスト内容の説明]
- [ ] テスト実行 → Red確認
- [ ] 実装: [実装内容の説明]
- [ ] テスト実行 → Green確認
- [ ] リファクタリング（必要な場合）
- [ ] Playwright MCP serverで動作確認（フロントエンド実装の場合）

## Phase 2: [フェーズ名]

### Task 2.1: [タスク名]
- **対応シナリオ**: requirement-spec.mdの[シナリオ名]
- [ ] テスト作成: [テスト内容の説明]
- [ ] テスト実行 → Red確認
- [ ] 実装: [実装内容の説明]
- [ ] テスト実行 → Green確認
- [ ] リファクタリング（必要な場合）
- [ ] Playwright MCP serverで動作確認（フロントエンド実装の場合）

## Phase 3: 統合テスト & ドキュメント

### Task 3.1: 統合テスト
- [ ] 統合テスト作成・実行
- [ ] 全テストがGreenであることを確認
- [ ] Playwright MCP serverでE2E動作確認（フロントエンド実装の場合）

### Task 3.2: ドキュメント更新
- [ ] [必要なドキュメントを更新]

Key Points:

• Break down into phases for gradual implementation
• Each task MUST follow TDD cycle: Test → Red → Implement → Green → Refactor
• Link each task to its corresponding scenario in requirement-spec.md
• For frontend implementations: Use Playwright MCP server to verify UI behavior after each task
• Time estimates are not required
• Track with TodoWrite tool during implementation

Draft Creation Workflow

Step 1: Initial Assessment

# Check existing RsDT
ls -la RsDT/

# Search related code with Grep
# (Example: searching for authentication-related implementation)

Step 2: Context Gathering

1. Understand Codebase

   • Read related files with Read tool
   • Search related code with Grep
   • Understand existing implementation patterns

2. Gather External Information

   • Get latest documentation via context7 MCP server
   • Get latest information via websearch
   • Understand libraries/frameworks to be used

3. Clarify Requirements

   • List unclear points
   • Ask questions with AskUserQuestion
   • Clarify requirements based on answers

Step 3: Feature Name Selection

# kebab-case, verb-led naming
FEATURE=add-user-authentication

# Create directory
mkdir -p RsDT/$FEATURE

Step 4: File Generation

# Generate 3 files (content will be in Japanese)
touch RsDT/$FEATURE/requirement-spec.md
touch RsDT/$FEATURE/design.md
touch RsDT/$FEATURE/tasks.md

Step 5: Draft Review (MANDATORY)

After creating the 3 draft files, you MUST call the rsdt-spec-reviewer sub-agent to review them.

Use the Task tool with subagent_type='rsdt-spec-reviewer' to verify that the created files comply with:

• Design Philosophy (Destructive Simplicity)
• Important Reminders
• File format requirements
• TDD workflow requirements

The reviewer will check the draft files against the current SKILL.md guidelines and provide feedback. Address any issues before proceeding to implementation.

Archive Guidelines

ADR Creation

IMPORTANT: ADRs should follow the project's existing language. Check existing ADRs to determine if they are in Japanese or English.

1. Determine if ADR is Needed

   • Check if project has ADR directory (e.g., docs/adr/, adr/)
   • Check if architecture-level decisions were made
   • Examples: Library selection, design pattern choice, data structure decisions

2. Review Existing ADRs

   • Read existing ADR files to understand format
   • Check naming conventions (e.g., 0001-use-markdown.md, ADR-001-database-choice.md)
   • Understand template structure being used

3. Create ADRs

   • Extract relevant architecture decisions from design.md
   • Create individual ADRs matching project format
   • Create one ADR file per decision

Design Doc Creation

IMPORTANT: Design Docs should be written in Japanese unless the project has existing design docs in English.

1. Determine if Design Doc is Needed

   • Is the design content worth referencing in the future?
   • Is it a complex feature that other developers need to understand?
   • Does the project have a location for design docs? (e.g., docs/design/, docs/specs/)

2. Create Design Doc

   • Extract important parts from requirement-spec.md and design.md
   • Summarize concisely:
     • Background and purpose
     • Key design decisions
     • Component composition
     • Important constraints
   • Place in appropriate project location

3. When Not Needed

   • For small bug fixes or simple feature additions, Design Doc is not needed
   • If implementation itself is clear enough as documentation, don't create

Implementation Guidelines

Stage 2 Implementation Notes

1. TDD (Test-Driven Development) Approach

   • MUST follow TDD cycle for each task: Red → Green → Refactor
   • Red: Write a failing test first based on requirement-spec.md scenarios
   • Green: Write minimal code to make the test pass
   • Refactor: Clean up code while keeping tests green
   • Never write implementation code without a failing test first

2. Utilize TodoWrite Tool

   • Register tasks.md content in TodoWrite at implementation start
   • Update each task from in_progress → completed
   • Keep only one task in in_progress state at a time

3. Sequential Implementation

   • Follow tasks.md order
   • Confirm completion per phase
   • Map tests to requirement scenarios

4. Completion Confirmation

   • All tasks completed
   • All tests passing
   • Update all checkboxes in tasks.md to [x]

TDD Workflow Per Task

For each task in tasks.md:
1. Identify the scenario from requirement-spec.md
2. Write test case (Red - test should fail)
3. Run test to confirm it fails
4. Write minimal implementation (Green - test should pass)
5. Run test to confirm it passes
6. Refactor if needed (keep tests green)
7. Mark task as completed

Design Philosophy

Destructive Simplicity

CRITICAL: Prioritize "modify/delete" over "add" during design

When designing, consider in this order:

1. Can this be achieved by deleting/consolidating existing code?

   • Remove duplicate code
   • Remove unused features
   • Merge multiple functions into one

2. Can this be achieved by making breaking changes to existing functions?

   • Change signatures (prefer simplicity over backward compatibility)
   • Reassign responsibilities
   • Simplify interfaces

3. Only add new code as a last resort

   • New functions/classes are the last option
   • When adding, simultaneously consider reducing existing code

Code Volume Principles

• Avoid net increase: Even when adding features, minimize total code increase through refactoring
• Reduce cognitive load: More functions/files = more cognitive load. Prefer consolidation
• Breaking changes are good: Directly modify rather than creating wrappers/adapters for backward compatibility

Mandatory Design Checklist

Before writing design.md, MUST verify:

• Have you read ALL related existing code?
• Is there code that can be deleted?
• Are there functions that can be consolidated?
• Can this be achieved by modifying existing functions?
• Is new code addition truly necessary?

Best Practices

Simplicity First

• Default to <100 lines of net new code (追加と削除の差分で計算)
• Single-file implementation unless clearly justified
• Be cautious about adding frameworks
• Choose boring, proven patterns
• Prefer modifying existing functions over creating new ones
• Delete code aggressively - dead code has negative value

When to Add Complexity

Only add complexity when:

• Performance data shows current solution is too slow
• Concrete scale requirements (>1000 users, >100MB data)
• Multiple proven use cases requiring abstraction
• Simpler alternatives have been explicitly ruled out

Clear References

• Reference code locations in file.ts:42 format
• Reference related features as RsDT/<feature_name>/

Feature Naming

• kebab-case, verb-noun format: add-user-auth, fix-payment-bug
• Single purpose per feature
• 10-minute understandability rule
• Split if description needs "AND"

Common Patterns

For Bug Fixes

requirement-spec.md (in Japanese):

# requirement-spec.md

## 背景・目的
[Bug description and impact scope]

## スコープ
### 実装すること
- バグの修正
- 関連テストの追加

### 実装しないこと
- 機能追加
- リファクタリング

## 要件・仕様
### バグ修正 - MODIFIED

#### 要件: [Existing Feature Name]
[Correct behavior after fix]

##### Scenario: バグ発生条件
- **GIVEN** [Conditions where bug occurs]
- **WHEN** [Actions]
- **THEN** [Expected behavior after fix]

For New Features

requirement-spec.md (in Japanese):

# requirement-spec.md

## 背景・目的
[Need for new feature]

## スコープ
### 実装すること
- 新機能A
- 新機能Aのテスト

### 実装しないこと
- 既存機能の変更
- 関連しない機能

## 要件・仕様
### 新機能 - ADDED

#### 要件: [New Feature Name]
[Feature description]

##### Scenario: 基本的な使用
- **GIVEN** [Preconditions]
- **WHEN** [Actions]
- **THEN** [Expected results]

##### Scenario: エラーケース
- **GIVEN** [Error conditions]
- **WHEN** [Actions]
- **THEN** [Error handling]

Troubleshooting

Common Issues

"Unclear what to implement"

• Re-check requirement-spec.md
• Ask user about unclear points
• Re-read related code

"Design is too complex"

• Return to Simplicity First principle
• Verify if complexity is truly needed
• Consider gradual implementation

"Tasks are not progressing"

• Review tasks.md phase breakdown
• Break down into smaller tasks
• Identify blockers and consult user

Quick Reference

Stage Indicators

• RsDT/<feature_name>/ - Work in progress (delete after completion)
• ADR - Architecture decision records (create as needed)
• Design Doc - Specifications to keep (create as needed)

File Purposes

• requirement-spec.md - What to build (requirements and specs, in Japanese)
• design.md - How to build (design, in Japanese)
• tasks.md - In what order to build (task breakdown, in Japanese)

Workflow Summary

Draft (Requirements) → Implementation (Build) → Archive (Create ADR/Design Doc, delete working directory)

Key Commands

# Check existing
ls -la RsDT/

# Create new
mkdir -p RsDT/<feature_name>

# Check implementation status
# Review checkboxes in tasks.md

# During Archive
# 1. Delete tasks.md
rm RsDT/<feature_name>/tasks.md

# 2. Create ADR/Design Doc (as needed)
# Check existing ADRs
ls -la docs/adr/  # or adr/

# 3. Delete working directory
rm -rf RsDT/<feature_name>/

Important Reminders

1. User input is memo-level: Must deepen understanding before generating 3 files
2. Understand code before asking: Get to a state where you can discuss before asking questions
3. Check latest info for external tools: Utilize context7 and websearch
4. Tests correspond to requirements: Always map scenarios to tests
5. Track with TodoWrite: Always use TodoWrite tool for progress management during implementation
6. Prioritize simplicity: Avoid excessive abstraction and complexity
7. RsDT is temporary directory: Create necessary documents after implementation completion and delete
8. ADR/Design Doc are selective: Only create when needed, follow existing format
9. Files in Japanese: All generated files (requirement-spec.md, design.md, tasks.md) must be in Japanese
10. Destructive Simplicity First: Always consider deleting/modifying existing code before adding new code. New functions are the LAST resort.
11. Minimize net code increase: Track lines added vs deleted. Aim for zero or negative net change when possible.
12. Breaking changes are acceptable: Prefer clean code over backward compatibility. Don't create wrappers just to avoid breaking changes.
13. TDD is mandatory: Always write tests first (Red), then implementation (Green), then refactor. Never write implementation without a failing test.
14. Document design alternatives: When multiple valid approaches exist, briefly document the options and why the chosen one was selected.
15. Draft review is mandatory: After creating draft files (requirement-spec.md, design.md, tasks.md), MUST call rsdt-spec-reviewer sub-agent to verify compliance with Design Philosophy and guidelines before proceeding to implementation.

Remember: Requirements are truth. Design guides implementation. Tasks track progress. RsDT is temporary. Files are in Japanese. Deletion before Addition. Test First. Review Before Implementation.