@tianhai/pi-workflow-kit 0.14.0 → 0.15.0

package/docs/plans/completed/2026-05-20-generic-lessons-design.md

@@ -0,0 +1,70 @@
+# Design: Enforce Generic Lessons in `docs/lessons.md`
+
+## Problem
+
+During `executing-tasks`, the agent writes lessons to `docs/lessons.md` scoped to the task at hand. In a monorepo, this produces domain-specific rules that are only useful within one feature or sprint — for example:
+
+> "Always validate `userId` before calling `UserProfile.Get`"
+
+The real lesson — applicable across any domain — would be:
+
+> "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
+
+Domain-specific rules decay immediately after the feature is done and pollute the lessons file for future work.
+
+## Goal
+
+Rules in `docs/lessons.md` should be generic patterns applicable to any domain or feature in the repo, not instances of a pattern tied to one service or entity.
+
+## Affected files
+
+- `skills/executing-tasks/SKILL.md`
+- `skills/finalizing/SKILL.md`
+
+## Changes
+
+### 1. `executing-tasks` — Step 6 "Learn from mistakes"
+
+Add a **generalization test** after "Only add rules that would change future behavior."
+
+```
+Before writing, apply the **generalization test**: would this rule apply equally to a
+completely different feature or domain in this repo? If not, rewrite it — strip out
+specific service names, entity types, and domain concepts, and express the underlying
+pattern instead. If you can't express a generic form, don't write the rule.
+
+❌ Domain-specific (only survives this sprint):
+   "Always validate `userId` before calling `UserProfile.Get`"
+
+✅ Generic (applies across the whole repo):
+   "Always validate required ID fields at the service boundary — missing IDs should
+    return 400, not 500"
+```
+
+### 2. `executing-tasks` — `docs/lessons.md` format template comment
+
+Add one line to the comment block so the constraint is visible every time the agent opens the file:
+
+```
+Rules must be generic patterns applicable to any domain or feature — not specific to
+one service, entity, or use case.
+```
+
+### 3. `finalizing` — Step 2 "Review lessons learned"
+
+Add a generalization audit bullet between "Add any lessons..." and "Retire rules...":
+
+```
+- Generalize domain-specific rules — if a rule names a specific service, entity, or
+  feature, either rewrite it as a generic pattern or remove it if no generic form exists
+```
+
+### 4. `finalizing` — `docs/lessons.md` format template comment
+
+Same addition as change 2 — keep both template definitions consistent.
+
+## Slice summary
+
+One end-to-end slice:
+
+> **Lessons stay generic** — at write-time (executing-tasks step 6) the agent is required to generalize before writing; the file's own comment reinforces the constraint; at finalization the agent audits and cleans up anything that slipped through.

package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md

@@ -0,0 +1,114 @@
+# Implementation Plan: Enforce Generic Lessons in `docs/lessons.md`
+
+Design: docs/plans/2026-05-20-generic-lessons-design.md
+
+Two skill files need four text edits total. No tests (markdown-only changes). Both
+tasks are trivial — exact old/new text is specified so the executor can apply them
+without guessing.
+
+---
+
+## Task 1: Add generalization test + update format comment in `executing-tasks`
+
+<!-- tdd: trivial -->
+
+File: `skills/executing-tasks/SKILL.md`
+
+Two edits in one file:
+
+### Edit A — Step 6 "Learn from mistakes"
+
+Replace:
+```
+6. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
+```
+
+With:
+```
+6. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
+
+   Before writing, apply the **generalization test**: would this rule apply equally to a completely different feature or domain in this repo? If not, rewrite it — strip out specific service names, entity types, and domain concepts, and express the underlying pattern instead. If you can't express a generic form, don't write the rule.
+
+   ❌ **Domain-specific** (only survives this sprint):
+   > "Always validate `userId` before calling `UserProfile.Get`"
+
+   ✅ **Generic** (applies across the whole repo):
+   > "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
+```
+
+### Edit B — `docs/lessons.md` format template comment
+
+Replace:
+```
+<!--
+Agent: read this at the start of each task during executing-tasks.
+Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Retire rules that no longer apply during finalizing.
+-->
+```
+
+With:
+```
+<!--
+Agent: read this at the start of each task during executing-tasks.
+Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
+Retire rules that no longer apply during finalizing.
+-->
+```
+
+Steps:
+1. Apply Edit A to `skills/executing-tasks/SKILL.md`
+2. Apply Edit B to `skills/executing-tasks/SKILL.md`
+3. Verify: open the file and confirm both edits are present and the surrounding text is intact
+
+---
+
+## Task 2: Add generalization audit bullet + update format comment in `finalizing`
+
+<!-- tdd: trivial -->
+
+File: `skills/finalizing/SKILL.md`
+
+Two edits in one file:
+
+### Edit A — Step 2 "Review lessons learned"
+
+Replace:
+```
+   - Add any lessons from this session that were missed during execution
+   - Retire rules that no longer apply (remove the bullet)
+```
+
+With:
+```
+   - Add any lessons from this session that were missed during execution
+   - **Generalize domain-specific rules** — if a rule names a specific service, entity, or feature, either rewrite it as a generic pattern or remove it if no generic form exists
+   - Retire rules that no longer apply (remove the bullet)
+```
+
+### Edit B — `docs/lessons.md` format template comment
+
+Replace:
+```
+<!--
+Agent: read this at the start of each task during executing-tasks.
+Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Retire rules that no longer apply during finalizing.
+-->
+```
+
+With:
+```
+<!--
+Agent: read this at the start of each task during executing-tasks.
+Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
+Retire rules that no longer apply during finalizing.
+-->
+```
+
+Steps:
+1. Apply Edit A to `skills/finalizing/SKILL.md`
+2. Apply Edit B to `skills/finalizing/SKILL.md`
+3. Verify: open the file and confirm both edits are present and the surrounding text is intact

package/docs/plans/completed/2026-05-20-generic-lessons-progress.md

@@ -0,0 +1,11 @@
+# Progress: generic-lessons
+
+Plan: docs/plans/2026-05-20-generic-lessons-implementation.md
+Branch: generic-lessons
+Started: 2026-05-20T00:00:00Z
+Last updated: 2026-05-20T00:00:00Z
+
+| # | Status | Task | Commit |
+|---|--------|------|--------|
+| 1 | ✅ done | Add generalization test + update format comment in `executing-tasks` | 96010f7 |
+| 2 | ✅ done | Add generalization audit bullet + update format comment in `finalizing` | 72f088d |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

package/skills/executing-tasks/SKILL.md

@@ -166,6 +166,14 @@ For each task:
 
    Run tests after each refactor step. Never refactor while tests are failing.
 6. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
+
+   Before writing, apply the **generalization test**: would this rule apply equally to a completely different feature or domain in this repo? If not, rewrite it — strip out specific service names, entity types, and domain concepts, and express the underlying pattern instead. If you can't express a generic form, don't write the rule.
+
+   ❌ **Domain-specific** (only survives this sprint):
+   > "Always validate `userId` before calling `UserProfile.Get`"
+
+   ✅ **Generic** (applies across the whole repo):
+   > "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
 7. **Commit** — after all steps are done (no checkpoint gates remain in the task), `git add` the relevant files and commit with a clear message.
 8. **Update progress** — mark `✅ done` + record the commit hash.
 9. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
@@ -188,6 +196,7 @@ For each task:
 <!--
 Agent: read this at the start of each task during executing-tasks.
 Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
 Retire rules that no longer apply during finalizing.
 -->
 

package/skills/finalizing/SKILL.md

@@ -37,6 +37,7 @@ Wait for the user to confirm before proceeding.
 
 2. **Review lessons learned** — if `docs/lessons.md` exists, review it:
    - Add any lessons from this session that were missed during execution
+   - **Generalize domain-specific rules** — if a rule names a specific service, entity, or feature, either rewrite it as a generic pattern or remove it if no generic form exists
    - Retire rules that no longer apply (remove the bullet)
    - If no changes are needed, leave it as-is
 
@@ -48,6 +49,7 @@ Wait for the user to confirm before proceeding.
    <!--
    Agent: read this at the start of each task during executing-tasks.
    Follow every rule. Add new rules when you catch yourself making repeat mistakes.
+   Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
    Retire rules that no longer apply during finalizing.
    -->