@xulthekl/team-flow 0.22.4

package/skills/ce-compound/references/lightweight-mode.md

@@ -0,0 +1,53 @@
+# Lightweight Mode — Detailed Workflow
+
+<critical_requirement>
+**Single-pass alternative — same artifact type, reduced research and validation.**
+
+This mode skips parallel subagents entirely. The orchestrator performs all work in a single pass and writes the same solution-doc artifact type, but omits cross-referencing, duplicate detection, session-history research, and semantic grounding validation.
+
+Headless mode enters Lightweight only when explicitly invoked with `depth:lightweight`; otherwise it defaults to Full for backward compatibility.
+</critical_requirement>
+
+The orchestrator (main conversation) performs ALL of the following in one sequential pass:
+
+1. **Extract from conversation**: Identify the problem and solution from conversation history. Also scan the "user's auto-memory" block injected into your system prompt, if present (Claude Code only) -- use any relevant notes as supplementary context alongside conversation history. Tag any memory-sourced content incorporated into the final doc with "(auto memory [claude])". Before asserting how code behaves (enum values, status semantics, limits, defaults), Read the defining line at the current tree — soften or attribute any claim you cannot verify. Cite PR numbers over bare commit SHAs, and phrase unmerged fixes as pending
+2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine track (bug vs knowledge), category, and filename
+3. **Write minimal doc**: Before writing, check whether the exact proposed `docs/solutions/[category]/[filename].md` path exists. If it exists, read it: update it only when it covers the same problem, preserving its path and frontmatter structure and adding `last_updated: YYYY-MM-DD`; otherwise choose a distinct, descriptive filename and re-check that exact path is absent before writing. This is exact-path collision handling only — do not run Full mode's semantic overlap research or dispatch subagents. Create or update the doc using the appropriate track template from `assets/resolution-template.md`, with:
+   - YAML frontmatter with track-appropriate fields, applying the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules)
+   - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
+   - Knowledge track: Context, guidance with key examples, one applicability note
+4. **Vocabulary capture (update-only)**: if `CONCEPTS.md` exists at repo root, read `references/concepts-vocabulary.md`, then scan the new doc and the conversation for qualifying terms and add/refine entries silently (same criteria as Phase 2.4). Do **not** bootstrap or seed in lightweight mode — if `CONCEPTS.md` does not exist, defer creation to a Full run, which owns seeding. Record the outcome in the output (e.g., "Vocabulary: 1 entry refined" or "scanned, no qualifying terms"). If you refined `CONCEPTS.md` and the project's active instructions and conventions already in your context do not surface it, add the discoverability tip to the output below — lightweight **tips**, it does not edit instruction files (an interactive Full run owns that edit after consent; headless Full also tips/reports only).
+5. **Read-only discoverability check**: Using the project's active instructions and conventions already in your context, assess whether they surface `docs/solutions/` against the three criteria under **Discoverability Check** in `references/full-mode-workflow.md`. Do not open, offer to edit, or edit instruction files; Lightweight only reports the result. Record one of:
+   - `no gap` when active project instructions surface the knowledge store
+   - `gap noted — instruction-file tip emitted` when active project instructions exist but do not surface it
+   - `not applicable — no active project instructions` when no project instructions are active; emit no discoverability tip
+6. **Mechanical claims check**: run `scripts/validate-doc-claims.py` against the written doc exactly as in Phase 2.45 step 1 (same `SKILL_DIR` anchor, same adjudicate-not-auto-fix rule — read `references/grounding-validation.md` for the adjudication table when it flags anything). Lightweight skips only the semantic validator subagent, not this deterministic check.
+7. **Frontmatter parser-safety check**: validate the written doc exactly as in Phase 2 step 8, using the same bundled-script existence guard and manual fallback checklist. Fix any violation and repeat the check; do not report success until the written frontmatter is parser-safe.
+8. **Skip specialized agent reviews** (Phase 3) and the semantic grounding validator (Phase 2.45 step 2) to conserve context
+
+## Lightweight Completion Output
+
+In headless Lightweight, do not emit this interactive block; use the depth-specific report under `references/output-standards.md` > `Headless mode` instead. In interactive Lightweight, emit:
+
+```
+✓ Documentation complete (lightweight mode)
+
+File created:
+- docs/solutions/[category]/[filename].md
+
+[If discoverability check found instruction files don't surface the knowledge store:]
+Tip: Your AGENTS.md/CLAUDE.md doesn't surface docs/solutions/ to agents —
+a brief mention helps all agents discover these learnings.
+
+[If CONCEPTS.md was refined this run and isn't surfaced in the instruction files:]
+Tip: Your AGENTS.md/CLAUDE.md doesn't surface CONCEPTS.md —
+a one-line mention helps agents find the shared vocabulary.
+
+Note: This was created in lightweight mode. For richer documentation
+(cross-references, detailed prevention strategies, specialized reviews,
+semantic grounding validation), re-run /ce-compound in a fresh session.
+```
+
+**No subagents are launched. No parallel tasks. The solution doc is the one deliverable** (Phase 2.4's update-only vocabulary capture may also refine an existing `CONCEPTS.md`).
+
+In lightweight mode, the overlap check is skipped (no Related Docs Finder subagent). This means lightweight mode may create a doc that overlaps with an existing one. That is acceptable — `ce-compound-refresh` will catch it later. Only suggest `ce-compound-refresh` if there is an obvious narrow refresh target. Do not broaden into a large refresh sweep from a lightweight session.

package/skills/ce-compound/references/output-standards.md

@@ -0,0 +1,182 @@
+# Output Standards & Common Mistakes
+
+## What It Captures
+
+- **Problem symptom**: Exact error messages, observable behavior
+- **Investigation steps tried**: What didn't work and why
+- **Root cause analysis**: Technical explanation
+- **Working solution**: Step-by-step fix with code examples
+- **Prevention strategies**: How to avoid in future
+- **Cross-references**: Links to related issues and docs
+
+## Categories (auto-detected from problem)
+
+Bug track:
+- build-errors/
+- test-failures/
+- runtime-errors/
+- performance-issues/
+- database-issues/
+- security-issues/
+- ui-bugs/
+- integration-issues/
+- logic-errors/
+
+Knowledge track:
+- architecture-patterns/ — architectural or structural patterns (agent/skill/pipeline/workflow shape decisions)
+- design-patterns/ — reusable non-architectural design approaches (content generation, interaction patterns, prompt shapes)
+- tooling-decisions/ — language, library, or tool choices with durable rationale
+- conventions/ — team-agreed way of doing something, captured so it survives turnover
+- workflow-issues/
+- developer-experience/
+- documentation-gaps/
+- best-practices/ — fallback only, use when no narrower knowledge-track value applies
+
+## Common Mistakes to Avoid
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| Subagents write product files into `docs/` or edit tracked paths | Subagents write only scratch artifacts under `<run-dir>/` and return the path; orchestrator writes the one final doc |
+| Subagent returns a long prose body only as its inline response | Subagent writes full output to its run artifact; orchestrator Reads it back (inline return is fallback only) |
+| Research and assembly run in parallel | Research completes → then assembly runs |
+| Multiple files created during workflow | One solution doc written or updated: `docs/solutions/[category]/[filename].md` (plus optional maintenance writes: a `CONCEPTS.md` create/update from Phase 2.4, and — interactive Full only, after consent — a small instruction-file edit for discoverability) |
+| Headless Discoverability Check edits AGENTS.md/CLAUDE.md | Headless Full reports `Instruction-file edit: gap noted, not applied`; headless Lightweight emits a discoverability tip; only interactive Full applies the edit after consent |
+| Creating a new doc when an existing doc covers the same problem | Check overlap assessment; update the existing doc when overlap is high |
+| Asserting code behavior or merge-state from conversation memory | Read the defining source line before asserting; cite PR numbers over SHAs; soften unverifiable claims (Phase 1 extractor rules, re-checked in Phase 2.45) |
+| Batching several learnings through one run and stitching cross-references between drafts | One learning per run; run the skill sequentially for each additional learning |
+
+## Success Output — Headless Mode
+
+Emit a structured terminal report and end the turn. No "What's next?" question, no blocking prompt. End with `Documentation complete` as the terminal signal so callers can detect completion.
+
+For `depth:lightweight`, use this lower-overhead report after the Lightweight Mode workflow:
+
+```
+✓ Documentation complete (headless lightweight mode)
+
+File: docs/solutions/<category>/<filename>.md  (created | updated)
+Track: <bug | knowledge>
+Category: <category>
+Grounding: <mechanical check clean | N flags adjudicated>
+Discoverability: <no gap | gap noted — instruction-file tip emitted | not applicable — no active project instructions>
+CONCEPTS.md: <not present | scanned, no qualifying terms | updated — N added, N refined>
+CONCEPTS.md discoverability: <not checked — CONCEPTS.md not refined | no gap | gap noted — instruction-file tip emitted | not applicable — no active project instructions>
+Refresh recommendation: <none | scope hint for /ce-compound-refresh>
+
+Documentation complete
+```
+
+For `depth:full` or backward-compatible headless calls with no depth token, use the Full report:
+
+```
+✓ Documentation complete (headless mode)
+
+File: docs/solutions/<category>/<filename>.md  (created | updated)
+Track: <bug | knowledge>
+Category: <category>
+Overlap: <none | low | moderate — see <path> | high — existing doc updated>
+Grounding: <clean | N flags adjudicated (X fixed, Y annotated, Z confirmed) | N claims softened or corrected | degraded — merge-state claims unverified offline>
+Instruction-file edit: <none needed | gap noted, not applied>
+CONCEPTS.md: <scanned, no qualifying terms | created with N entries (M seeded from the learning's area) | updated — N added, N refined>
+Refresh recommendation: <none | scope hint for /ce-compound-refresh>
+
+Documentation complete
+```
+
+When no doc was written (e.g., headless invoked on a session where the problem is not yet solved), emit a structured failure instead and end with `Documentation skipped` so callers can distinguish success from no-op:
+
+```
+✗ Documentation skipped (headless mode)
+
+Reason: <one-sentence explanation — e.g., "no solved problem detected in
+conversation history" or "solution not yet verified">
+
+Documentation skipped
+```
+
+## Success Output — Interactive Mode
+
+```
+✓ Documentation complete
+
+Ran Full mode.
+Auto memory: 2 relevant entries used as supplementary evidence
+
+Subagent Results:
+  ✓ Context Analyzer: Identified performance_issue in brief_system, category: performance-issues/
+  ✓ Solution Extractor: 3 code fixes, prevention strategies
+  ✓ Related Docs Finder: 2 related issues
+  ✓ Session History: 3 prior sessions on same branch, 2 failed approaches surfaced
+
+Grounding Validation:
+  ✓ Mechanical check: 14 paths, 2 SHAs, 3 links checked — 1 flag annotated as historical
+  ✓ Semantic validator: 9 claims verified, 1 merge-state claim softened to pending
+
+Specialized Agent Reviews (Auto-Triggered):
+  ✓ performance-oracle: Validated query optimization approach
+  ✓ Code simplification review: Code examples are appropriately minimal
+
+Files written:
+- docs/solutions/performance-issues/n-plus-one-brief-generation.md (created)
+- CONCEPTS.md (created with 3 entries: BriefSystem, EmailQueue, Brief Status)
+
+This documentation will be searchable for future reference when similar
+issues occur in the Email Processing or Brief System modules.
+
+Refresh recommendation: none
+```
+
+**End the turn after the summary — `ce-compound` does not present a "What's next?" menu.** The doc is written and any cross-references the workflow found are already in it. Cross-doc maintenance (fixing references in *other* docs, consolidation) is deferred to `ce-compound-refresh` via the `Refresh recommendation` line above — the skill designed for it — not auto-applied here, which would edit tracked docs beyond the one deliverable. If the user wants to view the file or take a follow-up action, they will ask. (Interactive mode only.)
+
+**Alternate interactive output (when updating an existing doc due to high overlap):** in headless mode, this case is communicated via the `Overlap: high — existing doc updated` line of the headless terminal report above, not as a separate output block.
+
+```
+✓ Documentation updated (existing doc refreshed with current context)
+
+Overlap detected: docs/solutions/performance-issues/n-plus-one-queries.md
+  Matched dimensions: problem statement, root cause, solution, referenced files
+  Action: Updated existing doc with fresher code examples and prevention tips
+
+File updated:
+- docs/solutions/performance-issues/n-plus-one-queries.md (added last_updated: 2026-03-24)
+```
+
+## The Compounding Philosophy
+
+This creates a compounding knowledge system:
+
+1. First time you solve "N+1 query in brief generation" → Research (30 min)
+2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
+3. Next time similar issue occurs → Quick lookup (2 min)
+4. Knowledge compounds → Team gets smarter
+
+The feedback loop:
+
+```
+Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
+    ↑                                                                      ↓
+    └──────────────────────────────────────────────────────────────────────┘
+```
+
+**Each unit of engineering work should make subsequent units of work easier—not harder.**
+
+## Applicable Specialized Local Prompts
+
+Based on problem type, these local prompt assets can enhance documentation:
+
+### Code Quality & Review
+- **Read-only code simplification review**: Checks solution examples and documentation claims for unnecessary complexity without mutating product code
+- **references/agents/pattern-recognition-specialist.md**: Identifies anti-patterns or repeating issues
+
+### Specific Domain Experts
+- **references/agents/performance-oracle.md**: Analyzes performance_issue category solutions
+- **references/agents/security-sentinel.md**: Reviews security_issue solutions for vulnerabilities
+- **references/agents/data-integrity-guardian.md**: Reviews database_issue migrations and queries
+
+### Enhancement & Research
+- **references/agents/best-practices-researcher.md**: Enriches solution with industry best practices
+- **references/agents/framework-docs-researcher.md**: Links to framework/library documentation references
+
+### When to Invoke
+- **Auto-triggered** (optional): Generic subagents seeded with local prompts can run post-documentation for enhancement
+- **Manual trigger**: User can run surviving skills such as `ce-simplify-code` after `/ce-compound` completes for deeper code review and mutation

package/skills/ce-compound/references/promotion-rules.md

@@ -0,0 +1,38 @@
+# 晋升检查规则
+
+## 触发时机
+
+release-archivist 归档时调用：
+
+```bash
+tf solutions promote <change-dir>
+```
+
+## 晋升来源
+
+检查 `specs/<cap>/learnings.md` 中的经验。
+
+## 晋升条件
+
+### change → product 晋升
+
+满足以下条件的经验从 change 级别晋升到全局 `docs/solutions/`：
+
+- **severity ≥ medium** 且 **type = pitfall 或 pattern** → 晋升到全局 `docs/solutions/`
+- 与全局 INDEX 中已有条目 **domain + type 匹配** → 标记"已确认模式"，severity 升级
+
+### Severity 标准
+
+| Severity | 含义 | 晋升行为 |
+|----------|------|----------|
+| high | 阻塞性问题或关键模式 | 必须晋升 |
+| medium | 有显著影响的问题或可复用模式 | 满足 type 条件时晋升 |
+| low | 轻微问题或局部洞察 | 不晋升，保留在 change 级别 |
+
+### 已确认模式
+
+当晋升的经验与全局 INDEX 中已有条目的 domain + type 匹配时：
+1. 不创建新文件
+2. 在已有条目中标记"已确认模式"
+3. severity 升级（low → medium, medium → high）
+4. 更新 INDEX.md 中对应行的 severity 字段

package/skills/ce-compound/references/schema.yaml

@@ -0,0 +1,231 @@
+# Documentation schema for learnings written by ce-compound
+# Treat this as the canonical frontmatter contract for docs/solutions/.
+#
+# The schema has two tracks based on problem_type:
+#   Bug track  — problem_type is a defect or failure (build_error, test_failure, etc.)
+#   Knowledge track — problem_type is guidance or practice (best_practice, workflow_issue, etc.)
+#
+# Both tracks share the same required core fields. The tracks differ in which
+# additional fields are required vs optional (see track_rules below).
+
+# --- Track classification ---------------------------------------------------
+tracks:
+  bug:
+    description: "Defects, failures, and errors that were diagnosed and fixed"
+    problem_types:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+  knowledge:
+    description: "Practices, patterns, conventions, decisions, workflow improvements, and documentation"
+    problem_types:
+      - best_practice
+      - documentation_gap
+      - workflow_issue
+      - developer_experience
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+
+# --- Fields required by BOTH tracks -----------------------------------------
+required_fields:
+  module:
+    type: string
+    description: "Module or area affected"
+
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date documented (YYYY-MM-DD)"
+
+  problem_type:
+    type: enum
+    values:
+      - build_error
+      - test_failure
+      - runtime_error
+      - performance_issue
+      - database_issue
+      - security_issue
+      - ui_bug
+      - integration_issue
+      - logic_error
+      - developer_experience
+      - workflow_issue
+      - best_practice
+      - documentation_gap
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+    description: "Primary category — determines track (bug vs knowledge). Prefer the narrowest applicable value; best_practice is the fallback when no narrower knowledge-track value fits."
+
+  component:
+    type: enum
+    values:
+      - rails_model
+      - rails_controller
+      - rails_view
+      - service_object
+      - background_job
+      - database
+      - frontend_stimulus
+      - hotwire_turbo
+      - email_processing
+      - brief_system
+      - assistant
+      - authentication
+      - payments
+      - development_workflow
+      - testing_framework
+      - documentation
+      - tooling
+    description: "Component involved"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity"
+
+# --- Track-specific rules ----------------------------------------------------
+track_rules:
+  bug:
+    required:
+      symptoms:
+        type: array[string]
+        min_items: 1
+        max_items: 5
+        description: "Observable symptoms such as errors or broken behavior"
+      root_cause:
+        type: enum
+        values:
+          - missing_association
+          - missing_include
+          - missing_index
+          - wrong_api
+          - scope_issue
+          - thread_violation
+          - async_timing
+          - memory_leak
+          - config_error
+          - logic_error
+          - test_isolation
+          - missing_validation
+          - missing_permission
+          - missing_workflow_step
+          - inadequate_documentation
+          - missing_tooling
+          - incomplete_setup
+        description: "Fundamental technical cause of the problem"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+          - seed_data_update
+        description: "Type of fix applied"
+
+  knowledge:
+    optional:
+      applies_when:
+        type: array[string]
+        max_items: 5
+        description: "Conditions or situations where this guidance applies"
+      symptoms:
+        type: array[string]
+        max_items: 5
+        description: "Observable gaps or friction that prompted this guidance (optional for knowledge track)"
+      root_cause:
+        type: enum
+        values:
+          - missing_association
+          - missing_include
+          - missing_index
+          - wrong_api
+          - scope_issue
+          - thread_violation
+          - async_timing
+          - memory_leak
+          - config_error
+          - logic_error
+          - test_isolation
+          - missing_validation
+          - missing_permission
+          - missing_workflow_step
+          - inadequate_documentation
+          - missing_tooling
+          - incomplete_setup
+        description: "Underlying cause, if there is a specific one (optional for knowledge track)"
+      resolution_type:
+        type: enum
+        values:
+          - code_fix
+          - migration
+          - config_change
+          - test_fix
+          - dependency_update
+          - environment_setup
+          - workflow_improvement
+          - documentation_update
+          - tooling_addition
+          - seed_data_update
+        description: "Type of change, if applicable (optional for knowledge track)"
+
+# --- Fields optional for BOTH tracks ----------------------------------------
+optional_fields:
+  related_components:
+    type: array[string]
+    description: "Other components involved"
+
+  tags:
+    type: array[string]
+    max_items: 8
+    description: "Search keywords, lowercase and hyphen-separated"
+
+# --- Fields optional for bug track only -------------------------------------
+bug_optional_fields:
+  rails_version:
+    type: string
+    pattern: '^\d+\.\d+\.\d+$'
+    description: "Rails version in X.Y.Z format. Only relevant for bug-track docs."
+
+# --- Backward compatibility --------------------------------------------------
+# Docs created before the track system was introduced may have bug-track
+# fields (symptoms, root_cause, resolution_type) on knowledge-type
+# problem_types. These are valid legacy docs:
+#   - Bug-track fields present on a knowledge-track doc are harmless. Do not
+#     strip them during refresh unless the doc is being rewritten for other reasons.
+#   - When creating NEW docs, follow the track rules above.
+
+# --- Validation rules --------------------------------------------------------
+validation_rules:
+  - "Determine track from problem_type using the tracks section above"
+  - "All shared required_fields must be present"
+  - "Bug-track required fields (symptoms, root_cause, resolution_type) must be present on bug-track docs"
+  - "Knowledge-track docs have no additional required fields beyond the shared ones"
+  - "Bug-track fields on existing knowledge-track docs are harmless (see backward compatibility note)"
+  - "Track-specific optional fields may be included but are not required"
+  - "Enum fields must match allowed values exactly"
+  - "Array fields must respect min_items/max_items when specified"
+  - "date must match YYYY-MM-DD format"
+  - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
+  - "tags should be lowercase and hyphen-separated"
+  - "Array-of-strings frontmatter items (symptoms, applies_when, tags, related_components, or any future array field) must be wrapped in double quotes when the value starts with a YAML reserved indicator (`, [, *, &, !, |, >, %, @, ?) or contains the substring `: ` — otherwise strict YAML parsers reject the file"

package/skills/ce-compound/references/three-tier-index.md

@@ -0,0 +1,55 @@
+# 三层索引架构
+
+## 目录结构
+
+```
+docs/solutions/
+├── INDEX.md                  # L1：轻量索引（≤150行，每条一行摘要+标签）
+├── prd/                      # 按阶段分目录
+├── plan/
+├── prototype/
+├── spec/
+├── build/
+├── review/
+└── cross-phase/              # 跨阶段通用经验
+```
+
+## INDEX.md 格式
+
+```markdown
+# Solutions Index
+<!-- 每条一行，按 severity 降序，≤150 行硬上限 -->
+| date | phase | domain | type | severity | summary | file |
+|------|-------|--------|------|----------|---------|------|
+```
+
+## 经验文件格式
+
+每条经验一个文件，frontmatter 包含标签：
+
+```yaml
+---
+phase: prd          # 阶段标签：prd | plan | prototype | spec | build | review | cross-phase
+domain: auth        # 领域标签（与 PRD/change 的领域对应）
+type: pitfall       # pitfall | pattern | decision | insight
+severity: high      # high | medium | low
+date: 2026-07-15
+source: change-id   # 来源 change（晋升时保留）
+---
+
+## 问题描述
+（一句话描述问题或经验）
+
+## 根因/模式
+（为什么会出现，或为什么这个模式有效）
+
+## 预防措施/应用方式
+（下次如何避免，或如何复用）
+```
+
+## 按需加载策略
+
+三层索引设计使最坏情况 token 消耗约 ~6.5k：
+1. **L1 INDEX.md**：始终加载（≤150 行，每条约 40 token）
+2. **L2 阶段目录**：按 phase 过滤后加载匹配文件列表
+3. **L3 经验文件**：仅加载与当前任务相关的具体文件

package/skills/ce-compound/references/v0.5-upgrade.md

@@ -0,0 +1,32 @@
+# v0.5 升级：复利贯穿引擎
+
+ce-compound 从"手动触发的记录工具"升级为"复利贯穿引擎的执行层"：
+
+| 现有能力 | v0.5 升级 |
+|---------|----------|
+| 手动调用 `/ce-compound` 记录 | 阶段转换点自动检测 + 手动补充 |
+| 写入 `docs/solutions/` 无索引 | 写入 INDEX.md + 分阶段目录（三层索引） |
+| 无阶段感知 | 按 phase/domain 标签过滤注入 |
+| 无晋升机制 | change→product 晋升规则 |
+| 全量加载 | 三层索引按需加载（最坏 ~6.5k token） |
+
+## 自动调用场景（v0.5 新增）
+
+除手动调用外，以下场景由流程自动触发 ce-compound 写入：
+
+- 原型审查发现 PRD 遗漏/矛盾（phase=prd, type=pitfall）
+- spec/design 被拒绝或大幅修改（phase=spec, type=pitfall）
+- bug-investigator 发现同类问题第 2 次（phase=build, type=pattern）
+- change 执行中超出原始 scope（phase=build, type=pitfall）
+- re-bridge 触发（phase=spec, type=pitfall）
+- mandatory rewind 触发（phase=cross-phase, type=pitfall）
+
+## 被流程自动调用
+
+各 skill 在阶段转换点通过 CLI 调用：
+
+```bash
+tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>"
+```
+
+此命令等价于手动调用 `/ce-compound` 但无需交互，直接写入。

package/skills/ce-compound/references/write-flow.md

@@ -0,0 +1,36 @@
+# 写入流程
+
+## 记录一条经验的步骤
+
+1. 确定 phase/domain/type/severity 标签
+2. 在对应阶段目录下创建经验文件（如 `docs/solutions/prd/2026-07-15-需求歧义.md`）
+3. 在 INDEX.md 中追加一行摘要
+4. 如果 INDEX.md 超过 150 行，执行淘汰规则
+
+## 淘汰规则（Eviction）
+
+当 INDEX.md 超过 150 行硬上限时：
+- 按 severity 降序排列（high > medium > low）
+- 保留前 150 条
+- 淘汰 low severity 且 date 最早的条目
+- 被淘汰的经验文件保留在阶段目录中（可从文件系统找回），仅从 INDEX.md 移除
+
+## CLI 写入命令
+
+各 skill 在阶段转换点通过 CLI 调用（无需交互）：
+
+```bash
+tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "<text>"
+```
+
+## 索引重建
+
+```bash
+tf solutions index-gen    # 重建复利索引
+```
+
+## 阶段感知注入
+
+```bash
+tf solutions inject --phase <p> --domain <d>   # 阶段感知注入（top-5）
+```