Initial commit

2025-11-30 08:37:19 +08:00
commit 8a09dce161
20 changed files with 6111 additions and 0 deletions
--- a/skills/pre-dev-subtask-creation/SKILL.md
+++ b/skills/pre-dev-subtask-creation/SKILL.md
@@ -0,0 +1,465 @@
+---
+name: pre-dev-subtask-creation
+description: |
+  Gate 8: Zero-context implementation steps - 2-5 minute atomic subtasks with
+  complete code, exact commands, TDD pattern. Large Track only.
+
+trigger: |
+  - Tasks passed Gate 7 validation
+  - Need absolute implementation clarity
+  - Creating work for engineers with zero codebase context
+  - Large Track workflow (2+ day features)
+
+skip_when: |
+  - Small Track workflow → execute tasks directly
+  - Tasks simple enough without breakdown
+  - Tasks not validated → complete Gate 7 first
+
+sequence:
+  after: [pre-dev-task-breakdown]
+  before: [executing-plans, subagent-driven-development]
+---
+
+# Subtask Creation - Bite-Sized, Zero-Context Steps
+
+## Overview
+
+Write comprehensive implementation subtasks assuming the engineer has zero context for our codebase. Each subtask breaks down into 2-5 minute steps following RED-GREEN-REFACTOR. Complete code, exact commands, explicit verification. **DRY. YAGNI. TDD. Frequent commits.**
+
+**Announce at start:** "I'm using the pre-dev-subtask-creation skill to create implementation subtasks."
+
+**Context:** This should be run after Gate 7 validation (approved tasks exist).
+
+**Save subtasks to:** `docs/pre-development/subtasks/T-[task-id]/ST-[task-id]-[number]-[description].md`
+
+## When to Use
+
+Use this skill when:
+- Tasks have passed Gate 7 validation
+- About to write implementation instructions
+- Tempted to write "add validation here..." (placeholder)
+- Tempted to say "update the user service" (which part?)
+- Creating work units for developers or AI agents
+
+**When NOT to use:**
+- Before Gate 7 validation
+- For trivial changes (<10 minutes total)
+- When engineer has full context (rare)
+
+## Foundational Principle
+
+**Every subtask must be completable by anyone with zero context about the system.**
+
+Requiring context creates bottlenecks, onboarding friction, and integration failures.
+
+**Subtasks answer**: Exactly what to create/modify, with complete code and verification.
+**Subtasks never answer**: Why the system works this way (context is removed).
+
+## Bite-Sized Step Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Subtask Document Header
+
+**Every subtask MUST start with this header:**
+
+```markdown
+# ST-[task-id]-[number]: [Subtask Name]
+
+> **For Agents:** REQUIRED SUB-SKILL: Use ring-default:executing-plans to implement this subtask step-by-step.
+
+**Goal:** [One sentence describing what this builds]
+
+**Prerequisites:**
+```bash
+# Verification commands
+cd /path/to/project
+npm list dependency-name
+# Expected output: dependency@version
+```
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+---
+```
+
+## Step Structure (TDD Cycle)
+
+```markdown
+### Step 1: Write the failing test
+
+```typescript
+// tests/exact/path/test.ts
+import { functionName } from '../src/module';
+
+describe('FeatureName', () => {
+  it('should do specific behavior', () => {
+    const result = functionName(input);
+    expect(result).toBe(expected);
+  });
+});
+```
+
+### Step 2: Run test to verify it fails
+
+```bash
+npm test tests/exact/path/test.ts
+# Expected output: FAIL - "functionName is not defined"
+```
+
+### Step 3: Write minimal implementation
+
+```typescript
+// src/exact/path/module.ts
+export function functionName(input: string): string {
+  return expected;
+}
+```
+
+### Step 4: Run test to verify it passes
+
+```bash
+npm test tests/exact/path/test.ts
+# Expected output: PASS - 1 test passed
+```
+
+### Step 5: Commit
+
+```bash
+git add tests/exact/path/test.ts src/exact/path/module.ts
+git commit -m "feat: add specific feature"
+```
+```
+
+## Explicit Rules
+
+### ✅ DO Include in Subtasks
+- Exact file paths (absolute or from root)
+- Complete file contents (if creating)
+- Complete code snippets (if modifying)
+- All imports and dependencies
+- Step-by-step TDD cycle (numbered)
+- Verification commands (copy-pasteable)
+- Expected output (exact)
+- Rollback procedures (exact commands)
+- Prerequisites (what must exist first)
+
+### ❌ NEVER Include in Subtasks
+- Placeholders: "...", "TODO", "implement here"
+- Vague instructions: "update the service", "add validation"
+- Assumptions: "assuming setup is done"
+- Context requirements: "you need to understand X first"
+- Incomplete code: "add the rest yourself"
+- Missing imports: "import necessary packages"
+- Undefined success: "make sure it works"
+- No verification: "test it manually"
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "The developer will figure out imports" | Imports are context. Provide them explicitly. |
+| "TODO comments are fine for simple parts" | TODOs require decisions. Make them now. |
+| "They'll know which service to update" | They won't. Specify the exact file path. |
+| "The verification steps are obvious" | Obvious ≠ documented. Write exact commands. |
+| "Rollback isn't needed for simple changes" | Simple changes fail too. Always provide rollback. |
+| "This needs system understanding" | Then you haven't removed context. Simplify more. |
+| "I'll provide the template, they fill it" | Templates are incomplete. Provide full code. |
+| "The subtask description explains it" | Descriptions need interpretation. Give exact steps. |
+| "They can look at similar code for reference" | That's context. Make subtask self-contained. |
+| "This is too detailed, we're not that formal" | Detailed = parallelizable = faster. Be detailed. |
+| "Steps are too small, feels like hand-holding" | Small steps = verifiable progress. Stay small. |
+
+## Red Flags - STOP
+
+If you catch yourself writing any of these in a subtask, **STOP and rewrite**:
+
+- Code placeholders: `...`, `// TODO`, `// implement X here`
+- Vague file references: "the user service", "the auth module"
+- Assumption phrases: "assuming you have", "make sure you"
+- Incomplete imports: "import required packages"
+- Missing paths: Not specifying where files go
+- Undefined verification: "test that it works"
+- Steps longer than 5 minutes
+- Context dependencies: "you need to understand X"
+- No TDD cycle in implementation steps
+
+**When you catch yourself**: Expand the subtask until it's completely self-contained.
+
+## Gate 8 Validation Checklist
+
+Before declaring subtasks ready:
+
+**Atomicity:**
+- [ ] Each step has single responsibility (2-5 minutes)
+- [ ] No step depends on understanding system architecture
+- [ ] Subtasks can be assigned to anyone (developer or AI)
+
+**Completeness:**
+- [ ] All code provided in full (no placeholders)
+- [ ] All file paths are explicit and exact
+- [ ] All imports listed explicitly
+- [ ] All prerequisites documented
+- [ ] TDD cycle followed in every implementation
+
+**Verifiability:**
+- [ ] Test commands are copy-pasteable
+- [ ] Expected output is exact (not subjective)
+- [ ] Commands run from project root (or specify directory)
+
+**Reversibility:**
+- [ ] Rollback commands provided
+- [ ] Rollback doesn't require system knowledge
+
+**Gate Result:**
+- ✅ **PASS**: All checkboxes checked → Ready for implementation
+- ⚠️ **CONDITIONAL**: Add missing details → Re-validate
+- ❌ **FAIL**: Too much context required → Decompose further
+
+## Example Subtask
+
+```markdown
+# ST-001-01: Create User Model with Validation
+
+> **For Agents:** REQUIRED SUB-SKILL: Use ring-default:executing-plans to implement this subtask step-by-step.
+
+**Goal:** Create a User model class with email and password validation in the auth service.
+
+**Prerequisites:**
+```bash
+cd /path/to/project
+npm list zod bcrypt
+# Expected: zod@3.22.4, bcrypt@5.1.1
+```
+
+**Files:**
+- Create: `src/domain/entities/User.ts`
+- Create: `src/domain/entities/__tests__/User.test.ts`
+- Modify: `src/domain/entities/index.ts`
+
+---
+
+### Step 1: Write the failing test
+
+Create file: `src/domain/entities/__tests__/User.test.ts`
+
+```typescript
+import { UserModel } from '../User';
+
+describe('UserModel', () => {
+  const validUserData = {
+    email: 'test@example.com',
+    password: 'securePassword123',
+    firstName: 'John',
+    lastName: 'Doe'
+  };
+
+  it('should create user with valid data', () => {
+    const user = new UserModel(validUserData);
+    expect(user.getData().email).toBe(validUserData.email);
+  });
+
+  it('should throw on invalid email', () => {
+    const invalidData = { ...validUserData, email: 'invalid' };
+    expect(() => new UserModel(invalidData)).toThrow('Invalid email format');
+  });
+});
+```
+
+### Step 2: Run test to verify it fails
+
+```bash
+npm test src/domain/entities/__tests__/User.test.ts
+# Expected: FAIL - "Cannot find module '../User'"
+```
+
+### Step 3: Write minimal implementation
+
+Create file: `src/domain/entities/User.ts`
+
+```typescript
+import { z } from 'zod';
+import bcrypt from 'bcrypt';
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email('Invalid email format'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+  firstName: z.string().min(1, 'First name is required'),
+  lastName: z.string().min(1, 'Last name is required'),
+  createdAt: z.date().default(() => new Date()),
+  updatedAt: z.date().default(() => new Date())
+});
+
+export type User = z.infer<typeof UserSchema>;
+
+export class UserModel {
+  private data: User;
+
+  constructor(data: Partial<User>) {
+    this.data = UserSchema.parse({
+      ...data,
+      id: data.id || crypto.randomUUID(),
+      createdAt: data.createdAt || new Date(),
+      updatedAt: data.updatedAt || new Date()
+    });
+  }
+
+  async hashPassword(): Promise<void> {
+    const saltRounds = 10;
+    this.data.password = await bcrypt.hash(this.data.password, saltRounds);
+  }
+
+  async comparePassword(candidatePassword: string): Promise<boolean> {
+    return bcrypt.compare(candidatePassword, this.data.password);
+  }
+
+  getData(): User {
+    return this.data;
+  }
+}
+```
+
+### Step 4: Run test to verify it passes
+
+```bash
+npm test src/domain/entities/__tests__/User.test.ts
+# Expected: PASS - 2 tests passed
+```
+
+### Step 5: Update exports
+
+Modify file: `src/domain/entities/index.ts`
+
+Add or append:
+```typescript
+export { UserModel, UserSchema, type User } from './User';
+```
+
+### Step 6: Verify type checking
+
+```bash
+npm run typecheck
+# Expected: No errors
+```
+
+### Step 7: Commit
+
+```bash
+git add src/domain/entities/User.ts src/domain/entities/__tests__/User.test.ts src/domain/entities/index.ts
+git commit -m "feat: add User model with validation
+
+- Add Zod schema for user validation
+- Implement password hashing with bcrypt
+- Add comprehensive tests"
+```
+
+### Rollback
+
+If issues occur:
+```bash
+rm src/domain/entities/User.ts
+rm src/domain/entities/__tests__/User.test.ts
+git checkout -- src/domain/entities/index.ts
+git status
+```
+```
+
+## Confidence Scoring
+
+Use this to adjust your interaction with the user:
+
+```yaml
+Confidence Factors:
+  Step Atomicity: [0-30]
+    - All steps 2-5 minutes: 30
+    - Most steps appropriately sized: 20
+    - Steps too large or vague: 10
+
+  Code Completeness: [0-30]
+    - Zero placeholders, all code complete: 30
+    - Mostly complete with minor gaps: 15
+    - Significant placeholders or TODOs: 5
+
+  Context Independence: [0-25]
+    - Anyone can execute without questions: 25
+    - Minor context needed: 15
+    - Significant domain knowledge required: 5
+
+  TDD Coverage: [0-15]
+    - All implementation follows RED-GREEN-REFACTOR: 15
+    - Most steps include tests: 10
+    - Limited test coverage: 5
+
+Total: [0-100]
+
+Action:
+  80+: Generate complete subtasks autonomously
+  50-79: Present approach options for complex steps
+  <50: Ask about codebase structure and patterns
+```
+
+## Execution Handoff
+
+After creating subtasks, offer execution choice:
+
+**"Subtasks complete and saved to `docs/pre-development/subtasks/T-[id]/`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per subtask, review between subtasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use ring-default:subagent-driven-development
+- Stay in this session
+- Fresh subagent per subtask + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- **REQUIRED SUB-SKILL:** New session uses ring-default:executing-plans
+
+## Quality Self-Check
+
+Before declaring subtasks complete, verify:
+- [ ] Every step is truly atomic (2-5 minutes)
+- [ ] Zero context required to complete any step
+- [ ] All code is complete (no "...", "TODO", placeholders)
+- [ ] All file paths are explicit (absolute or from root)
+- [ ] All imports are listed explicitly
+- [ ] TDD cycle followed (test → fail → implement → pass → commit)
+- [ ] Verification steps included with exact commands
+- [ ] Expected output specified for every command
+- [ ] Rollback plans provided with exact commands
+- [ ] Prerequisites documented (what must exist first)
+- [ ] Gate 8 validation checklist 100% complete
+
+## The Bottom Line
+
+**If you wrote a subtask with "TODO" or "..." or "add necessary imports", delete it and rewrite with complete code.**
+
+Subtasks are not instructions. Subtasks are complete, copy-pasteable implementations following TDD.
+
+- "Add validation" is not a step. [Complete validation code with test] is a step.
+- "Update the service" is not a step. [Exact file path + exact code changes with test] is a step.
+- "Import necessary packages" is not a step. [Complete list of imports] is a step.
+
+Every subtask must be completable by someone who:
+- Just joined the team yesterday
+- Has never seen the codebase before
+- Doesn't know the business domain
+- Won't ask questions (you're unavailable)
+- Follows TDD religiously
+
+If they can't complete it with zero questions while following RED-GREEN-REFACTOR, **it's not atomic enough.**
+
+**Remember: DRY. YAGNI. TDD. Frequent commits.**