ClawKK

---
name: authz
description: "Permissions, roles, policies, and enforcement points. Use when designing RBAC/ABAC or fixing authZ holes."
---

# AuthZ

Structured guidance for **authorization** (RBAC, ABAC, policy enforcement): confirm triggers, propose the stages below, and adapt if the user wants a lighter pass.

## When to Offer This Workflow

**Trigger conditions:**
- User mentions **authorization**, **authZ**, **permissions**, or closely related work
- They want a structured workflow rather than ad-hoc tips
- They are preparing a review, rollout, or stakeholder communication

**Initial offer:**
Explain the four stages briefly and ask whether to follow this workflow or work freeform. If they decline, continue in their preferred style.

## Workflow Stages

### Stage 1: Clarify context & goals

Anchor on **model: RBAC/ABAC/ReBAC**. Ask what success looks like, constraints, and what must not break. Capture unknowns early.

### Stage 2: Design or plan the approach

Translate goals into a concrete plan around **policy enforcement points**. Compare alternatives and explicit trade-offs; avoid implicit assumptions.

### Stage 3: Implement, validate, and harden

Execute with verification loops tied to **auditing and admin paths**. Prefer small steps, measurable checks, and rollback points where risk is high.

### Stage 4: Operate, communicate, and iterate

Close the loop with **testing negative cases**: monitoring, documentation, stakeholder updates, and lessons learned for the next cycle.

## Checklist Before Completion

- Goals and constraints are explicit for **authZ**
- Risks and trade-offs are stated, not hand-waved
- Verification steps match the change’s impact (tests, canary, peer review)
- Operational follow-through is covered (monitoring, docs, owners)

## Tips for Effective Guidance

- Be procedural: stage-by-stage, with clear exit criteria
- Ask for missing context (environment, scale, deadlines) before prescribing
- Prefer checklists and concrete examples over generic platitudes
- If the user declines the workflow, switch to freeform help without lecturing

## Handling Deviations

- If the user wants to skip a stage: confirm and continue with what they need.
- If context is missing: ask targeted questions before strong recommendations.
- Prefer concrete examples, trade-offs, and verification steps over generic advice.

## Quality Bar

- Each recommendation should be **actionable** (what to do next).
- Call out **failure modes** relevant to authorization (security, scale, UX, or ops).
- Keep tone direct and respectful of the user’s time.

---
name: asyncio
description: "asyncio patterns, concurrency pitfalls, and backpressure. Use when writing async Python services."
---

# Asyncio

Structured guidance for **async Python** with **asyncio**: confirm triggers, propose the stages below, and adapt if the user wants a lighter pass.

## When to Offer This Workflow

**Trigger conditions:**
- User mentions **asyncio**, **async python**, or closely related work
- They want a structured workflow rather than ad-hoc tips
- They are preparing a review, rollout, or stakeholder communication

**Initial offer:**
Explain the four stages briefly and ask whether to follow this workflow or work freeform. If they decline, continue in their preferred style.

## Workflow Stages

### Stage 1: Clarify context & goals

Anchor on **event loop and tasks**. Ask what success looks like, constraints, and what must not break. Capture unknowns early.

### Stage 2: Design or plan the approach

Translate goals into a concrete plan around **cancellation and timeouts**. Compare alternatives and explicit trade-offs; avoid implicit assumptions.

### Stage 3: Implement, validate, and harden

Execute with verification loops tied to **backpressure and queues**. Prefer small steps, measurable checks, and rollback points where risk is high.

### Stage 4: Operate, communicate, and iterate

Close the loop with **debugging concurrency**: monitoring, documentation, stakeholder updates, and lessons learned for the next cycle.

## Checklist Before Completion

- Goals and constraints are explicit for **asyncio** work
- Risks and trade-offs are stated, not hand-waved
- Verification steps match the change’s impact (tests, canary, peer review)
- Operational follow-through is covered (monitoring, docs, owners)

## Tips for Effective Guidance

- Be procedural: stage-by-stage, with clear exit criteria
- Ask for missing context (environment, scale, deadlines) before prescribing
- Prefer checklists and concrete examples over generic platitudes
- If the user declines the workflow, switch to freeform help without lecturing

## Handling Deviations

- If the user wants to skip a stage: confirm and continue with what they need.
- If context is missing: ask targeted questions before strong recommendations.
- Prefer concrete examples, trade-offs, and verification steps over generic advice.

## Quality Bar

- Each recommendation should be **actionable** (what to do next).
- Call out **failure modes** relevant to asyncio concurrency (security, scale, UX, or ops).
- Keep tone direct and respectful of the user’s time.

---
name: deps-mgmt
description: Deep dependency management workflow—inventory, upgrade policy, security patches, licensing, lockfiles, and supply-chain hygiene. Use when upgrading frameworks, resolving CVEs, or standardizing how teams pin dependencies.
---

# Dependencies

Dependencies are **supply-chain** surface area: versions affect security, reproducibility, and upgrade cost.

## When to Offer This Workflow

**Trigger conditions:**

- Dependabot noise; major version upgrades
- CVE response or license audit
- “Works on my machine” due to unpinned dependencies

**Initial offer:**

Use **six stages**: (1) inventory & risk, (2) policy & cadence, (3) lockfiles & reproducibility, (4) upgrades & testing, (5) security & licensing, (6) governance & tooling). Confirm ecosystem (npm, pip, Maven, Go modules, etc.).

---

## Stage 1: Inventory & Risk

**Goal:** Direct vs transitive dependencies; flag critical packages (crypto, auth, parsing, serialization).

**Exit condition:** SBOM or export for top applications; list of critical deps.

---

## Stage 2: Policy & Cadence

**Goal:** When to upgrade (time-based vs on-demand); SemVer rules for libraries vs applications.

---

## Stage 3: Lockfiles & Reproducibility

**Goal:** Committed lockfiles for deployable apps; libraries test against a compatibility matrix instead of one frozen lock.

---

## Stage 4: Upgrades & Testing

**Goal:** Prefer one major bump per PR when feasible; CI matrix on supported language/runtime versions.

---

## Stage 5: Security & Licensing

**Goal:** SCA scanning; patch SLA by severity; license allowlist for compliance.

---

## Stage 6: Governance & Tooling

**Goal:** Renovate/Bot policies; pin internal packages; document exceptions and overrides.

---

## Final Review Checklist

- [ ] Inventory and risk hotspots known
- [ ] Upgrade cadence and semver policy documented
- [ ] Lockfiles or matrix strategy per repo type
- [ ] CI validates upgrades
- [ ] SCA and license policy enforced

## Tips for Effective Guidance

- Transitive CVEs may need overrides—trace the dependency graph.
- Pin CI images and toolchains, not only application dependencies.

## Handling Deviations

- Monorepos: shared versions with Nx/Bazel/etc.—coordinate breaking upgrades.

---
name: db-migrate
description: Deep database migration workflow—expand/contract, backward-compatible deploys, backfills, locking risks, and verification. Use when changing production schemas safely with zero or low downtime.
---

# DB Migrations

Production schema changes fail when old and new code disagree during rollout. Prefer **expand/contract**: add compatible changes first, remove old shapes later.

## When to Offer This Workflow

**Trigger conditions:**

- ALTER TABLE in production; large table rewrites
- Blue/green deploys coupled to schema state
- Need zero-downtime or low-downtime migrations

**Initial offer:**

Use **six stages**: (1) classify change, (2) expand phase, (3) backfill & dual-write, (4) flip reads/writes, (5) contract phase, (6) verify & rollback). Confirm database engine (PostgreSQL, MySQL, etc.).

---

## Stage 1: Classify Change

**Goal:** Additive vs destructive; lock risk (full table rewrite vs instant metadata change).

**Exit condition:** Migration labeled as expand or contract with risk notes.

---

## Stage 2: Expand Phase

**Goal:** Add nullable columns or new tables without breaking currently deployed code.

### Practices

- Avoid DEFAULT clauses that lock large tables badly on some engines (use phased backfill instead)

---

## Stage 3: Backfill & Dual-Write

**Goal:** Throttled batch backfill; dual-write old and new representations during transition when needed.

---

## Stage 4: Flip Reads/Writes

**Goal:** Deploy code that reads new columns only after backfill completes; use feature flags for staged rollout.

---

## Stage 5: Contract Phase

**Goal:** Drop old columns only after no code references them (search repo, logs, feature usage).

---

## Stage 6: Verify & Rollback

**Goal:** Monitor errors, slow queries, replication lag; rollback = redeploy previous app version + avoid destructive steps until stable.

---

## Final Review Checklist

- [ ] Change classified; expand/contract path clear
- [ ] Additive migrations before dependent code
- [ ] Backfill throttled and verified
- [ ] Read/write cutover sequenced with flags
- [ ] Contract only after references gone
- [ ] Monitoring and rollback tested

## Tips for Effective Guidance

- Long transactions on migrations can cause outages—chunk work.
- Use online schema tools (pt-online-schema-change, etc.) when appropriate.

## Handling Deviations

- SQLite/embedded engines have different locking—validate per engine.

---
name: db-design
description: Deep database design workflow—entities and relationships, keys and constraints, normalization vs denormalization, indexing strategy, integrity, and operational concerns. Use when designing OLTP schemas or reviewing greenfield data models.
---

# DB Design

Good OLTP design balances integrity, write paths, query patterns, and evolution—not “third normal form everywhere.”

## When to Offer This Workflow

**Trigger conditions:**

- Greenfield service schema or major new domain
- Performance or integrity issues from ad-hoc tables
- Multi-tenant isolation questions

**Initial offer:**

Use **six stages**: (1) domain & access patterns, (2) entities & relationships, (3) keys & constraints, (4) normalization trade-offs, (5) indexing & performance, (6) operations & evolution). Confirm RDBMS and scale expectations.

---

## Stage 1: Domain & Access Patterns

**Goal:** List critical queries and writes: QPS, joins, filters, hot rows.

**Exit condition:** Top access paths ranked by business importance.

---

## Stage 2: Entities & Relationships

**Goal:** ER model; cardinality; optional vs required relationships.

### Practices

- Clear table names; avoid opaque “data” blobs unless documented

---

## Stage 3: Keys & Constraints

**Goal:** Primary keys (surrogate vs natural); foreign keys with explicit ON DELETE policy; unique constraints for business rules.

### Multi-tenant

- `tenant_id` on rows that need isolation; composite keys or indexes as appropriate

---

## Stage 4: Normalization Trade-offs

**Goal:** Normalize to reduce update anomalies; denormalize read hotspots with documented trade-offs.

---

## Stage 5: Indexing & Performance

**Goal:** Indexes serve real queries; watch write amplification and index bloat.

---

## Stage 6: Operations & Evolution

**Goal:** Migration strategy (expand/contract); backup/restore; PII columns flagged.

---

## Final Review Checklist

- [ ] Access patterns drive schema
- [ ] Keys, FKs, and constraints explicit
- [ ] Multi-tenant isolation if applicable
- [ ] Normalization decisions justified
- [ ] Index plan aligned with queries
- [ ] Migration and ops considerations noted

## Tips for Effective Guidance

- NULL semantics and defaults matter for bugs and migrations.
- Pair with **db-migrate** for online schema changes.

## Handling Deviations

- Document stores: embed vs reference with consistency story.

---
name: startup-validator
description: Startup validation before you build—structured validate, compete, and mvp commands plus a reporting template. Use when the user wants to sanity-check a startup idea, competitive landscape, MVP scope, or early PMF thinking. Keywords: startup validation, founder, competitive analysis, MVP, PMF, indie hacker.
---

# Startup Validator — Structure Your Validation Before You Build

## Overview

Helps founders and indie hackers **structure** early validation: market-fit signals, competitive landscape, and MVP scope. Clearer than a generic “idea check”—it’s framed around **starting up** (problem, market, and first ship).

**Trigger keywords**: startup validation, founder idea check, competitive analysis, MVP scope, PMF, pre-launch

## Prerequisites

```bash
pip install requests
```

*(Optional if you extend the tool to call external APIs; the bundled script uses the Python stdlib.)*

## Capabilities

1. **Multi-dimensional review** — market, competitors, tech stack, business model (see `references/startup_validator_guide.md`).
2. **Persona & need framing** — who pays and what job-to-be-done is.
3. **MVP & roadmap sketch** — a realistic first release slice.

## Commands

| Command | Description | Example |
|---------|-------------|---------|
| `validate` | Validation pass for an idea | `python3 scripts/startup_validator_tool.py validate [args]` |
| `compete` | Competitive landscape pass | `python3 scripts/startup_validator_tool.py compete [args]` |
| `mvp` | MVP plan scaffold | `python3 scripts/startup_validator_tool.py mvp [args]` |

## Usage (from repository root)

```bash
python3 scripts/skills/startup-validator/scripts/startup_validator_tool.py validate --idea 'SaaS bookkeeping'
python3 scripts/skills/startup-validator/scripts/startup_validator_tool.py compete --market 'bookkeeping'
python3 scripts/skills/startup-validator/scripts/startup_validator_tool.py mvp --idea 'SaaS bookkeeping'
```

## Output format (for the agent’s report)

```markdown
# Startup validation report

**Generated**: YYYY-MM-DD HH:MM

## Key findings
1. [Finding 1]
2. [Finding 2]
3. [Finding 3]

## Data snapshot
| Metric | Value | Trend | Rating |
|--------|-------|-------|--------|
| A | XXX | ↑ | ⭐⭐⭐⭐ |
| B | YYY | → | ⭐⭐⭐ |

## Analysis
[Multi-dimensional analysis grounded in data you actually have]

## Recommendations
| Priority | Action | Expected impact |
|----------|--------|-----------------|
| High | [Action] | [Quantify if possible] |
| Medium | [Action] | … |
| Low | [Action] | … |
```

## References

### Core links
- [YC: The real product/market fit](https://www.ycombinator.com/library/5z-the-real-product-market-fit)
- [Pre-build idea validator use case (OpenClaw)](https://github.com/hesamsheikh/awesome-openclaw-usecases/blob/main/usecases/pre-build-idea-validator.md)
- [Market research product factory use case](https://github.com/hesamsheikh/awesome-openclaw-usecases/blob/main/usecases/market-research-product-factory.md)

### Community
- [Hacker News discussion](https://news.ycombinator.com/item?id=41986396)
- [Reddit r/startups — related thread](https://www.reddit.com/r/startups/comments/1055d61yyz/idea_validator_ai/)

## Notes

- Prefer **real** data from APIs, search, or user-provided sources; do not invent metrics.
- Mark missing data as **unavailable** instead of guessing.
- Treat AI output as **input to judgment**, not a go/no-go by itself.
- Optional: `pip install requests` if you extend the script with HTTP calls.

## Legacy name

This skill was previously published as **`idea-validator`**. The slug is now **`startup-validator`** (friendlier for “founder / startup” workflows). If an old path is bookmarked, migrate to `scripts/skills/startup-validator/`.

FILE:data/startup_validator_data.json
{
  "records": [
    {
      "timestamp": "2026-03-25T14:45:00.634895",
      "command": "validate",
      "input": "",
      "status": "completed"
    }
  ],
  "created": "2026-03-25T14:45:00.634882",
  "tool": "startup-validator"
}
FILE:references/startup_validator_guide.md
# Startup Validator — Analysis Framework & Guide

## Tool summary

- **Name**: Startup Validator  
- **Commands**: `validate` (validation pass), `compete` (competitive analysis), `mvp` (MVP scaffold)  
- **Optional dependency**: `pip install requests` (if you add HTTP calls)

## Analysis dimensions

- Multi-dimensional review — market / competitors / technology / business model  
- Persona and need validation  
- MVP scope and roadmap sketch  

## Framework

### Phase 1: Data collection
- Define sources and scope  
- Normalize inputs  
- Establish baseline comparison metrics  

### Phase 2: Insight & patterns
- Cross-cutting analysis  
- Trend and anomaly detection  
- Root-cause hypotheses where data supports them  

### Phase 3: Actions & decisions
- Concrete, prioritized recommendations  
- Risk register and mitigations  

## Scoring rubric

| Score | Level | Meaning | Suggested action |
|-------|-------|---------|------------------|
| 5 | ⭐⭐⭐⭐⭐ | Far above bar | Pursue aggressively |
| 4 | ⭐⭐⭐⭐ | Above bar | Prioritize |
| 3 | ⭐⭐⭐ | Meets bar | Optional improvements |
| 2 | ⭐⭐ | Below bar | Fix gaps before scaling |
| 1 | ⭐ | Fails bar | Reconsider or pivot |

## Output template

```markdown
# Startup validation analysis
## Key findings
1. …
2. …

## Evidence
| Metric | Value | Trend | Rating |
|--------|-------|-------|--------|

## Recommendations
| Priority | Action | Rationale | Expected impact |
|----------|--------|-----------|-------------------|
```

## Reference links

### Core
- [YC: The real product/market fit](https://www.ycombinator.com/library/5z-the-real-product-market-fit)
- [Pre-build idea validator (OpenClaw)](https://github.com/hesamsheikh/awesome-openclaw-usecases/blob/main/usecases/pre-build-idea-validator.md)
- [Market research product factory](https://github.com/hesamsheikh/awesome-openclaw-usecases/blob/main/usecases/market-research-product-factory.md)

### Community
- [Hacker News](https://news.ycombinator.com/item?id=41986396)
- [Reddit r/startups](https://www.reddit.com/r/startups/comments/1055d61yyz/idea_validator_ai/)

## Tips

1. Adapt the framework to stage (problem discovery vs GTM).  
2. Weight criteria by risk tolerance (e.g. regulated markets).  
3. Combine quantitative signals with qualitative interviews.  
4. Use the links as **starting points** for research, not as proof alone.  

FILE:scripts/startup_validator_tool.py
#!/usr/bin/env python3
"""
Startup validator — CLI helper for validate / compete / mvp flows.

Usage:
    python3 startup_validator_tool.py validate [args]   # validation pass
    python3 startup_validator_tool.py compete [args]    # competitive analysis pass
    python3 startup_validator_tool.py mvp [args]          # MVP scaffold pass
"""

import json
import os
import sys
from datetime import datetime

DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "data")
DATA_FILE = os.path.join(DATA_DIR, "startup_validator_data.json")
LEGACY_DATA_FILE = os.path.join(DATA_DIR, "idea_validator_data.json")

REF_URLS = [
    "https://www.ycombinator.com/library/5z-the-real-product-market-fit",
    "https://github.com/hesamsheikh/awesome-openclaw-usecases/blob/main/usecases/pre-build-idea-validator.md",
    "https://github.com/hesamsheikh/awesome-openclaw-usecases/blob/main/usecases/market-research-product-factory.md",
    "https://news.ycombinator.com/item?id=41986396",
    "https://www.reddit.com/r/startups/comments/1055d61yyz/idea_validator_ai/",
]


def ensure_data_dir():
    os.makedirs(DATA_DIR, exist_ok=True)


def load_data():
    if os.path.exists(DATA_FILE):
        with open(DATA_FILE, "r", encoding="utf-8") as f:
            return json.load(f)
    if os.path.exists(LEGACY_DATA_FILE):
        with open(LEGACY_DATA_FILE, "r", encoding="utf-8") as f:
            data = json.load(f)
        data["tool"] = "startup-validator"
        save_data(data)
        return data
    return {"records": [], "created": datetime.now().isoformat(), "tool": "startup-validator"}


def save_data(data):
    ensure_data_dir()
    with open(DATA_FILE, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)


def validate(args):
    """Run startup / idea validation flow."""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "validate",
        "input": " ".join(args) if args else "",
        "status": "completed",
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "validate",
        "message": "Validation step completed",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3],
    }


def compete(args):
    """Run competitive analysis flow."""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "compete",
        "input": " ".join(args) if args else "",
        "status": "completed",
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "compete",
        "message": "Competitive analysis step completed",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3],
    }


def mvp(args):
    """Run MVP scaffold flow."""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "mvp",
        "input": " ".join(args) if args else "",
        "status": "completed",
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "mvp",
        "message": "MVP scaffold step completed",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3],
    }


def main():
    cmds = ["validate", "compete", "mvp"]
    if len(sys.argv) < 2 or sys.argv[1] not in cmds:
        print(
            json.dumps(
                {
                    "error": f"Usage: startup_validator_tool.py <{','.join(cmds)}> [args]",
                    "available_commands": {c: "" for c in cmds},
                    "tool": "startup-validator",
                },
                ensure_ascii=False,
                indent=2,
            )
        )
        sys.exit(1)

    cmd = sys.argv[1]
    args = sys.argv[2:]

    if cmd == "validate":
        result = validate(args)
    elif cmd == "compete":
        result = compete(args)
    elif cmd == "mvp":
        result = mvp(args)
    else:
        result = {"error": f"Unknown command: {cmd}"}

    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))


if __name__ == "__main__":
    main()

---
name: habit-coach
description: "习惯养成教练。充当AI问责伙伴，帮助建立、追踪和坚持好习惯。Keywords: 习惯养成, 自律, habit tracker, 打卡."
---

## 概述

充当AI问责伙伴，帮助建立、追踪和坚持好习惯。适用于日常习惯打卡、目标进度追踪、行为模式分析等场景。awesome-openclaw-usecases收录：带问责机制的习惯追踪器。

## 适用范围

**适用场景**：
- 每日习惯打卡记录
- 查看习惯连续坚持天数
- 制定新的习惯养成计划

**不适用场景**：
- 需要实时硬件控制或低延迟响应的场景
- 涉及敏感个人隐私数据的未授权处理

**触发关键词**: 习惯养成, 自律, habit tracker, 打卡, 问责

## 前置条件

```bash
pip install requests
```

> ⚠️ 首次使用前请确认依赖已安装，否则脚本将无法运行。

## 核心能力

### 能力1：个性化习惯计划制定与打卡追踪
个性化习惯计划制定与打卡追踪

### 能力2：AI问责伙伴——鼓励/提醒/分析原因
AI问责伙伴——鼓励/提醒/分析原因

### 能力3：习惯数据可视化与行为模式洞察
习惯数据可视化与行为模式洞察


## 命令列表

| 命令 | 说明 | 用法 |
|------|------|------|
| `track` | 习惯打卡 | `python3 scripts/habit_coach_tool.py track [参数]` |
| `review` | 进度回顾 | `python3 scripts/habit_coach_tool.py review [参数]` |
| `plan` | 制定计划 | `python3 scripts/habit_coach_tool.py plan [参数]` |


## 处理步骤

### Step 1：习惯打卡

**目标**：打卡今日运动和阅读

**为什么这一步重要**：这是整个工作流的数据采集/初始化阶段，确保后续步骤基于准确的输入。

**执行**：
```bash
python3 scripts/habit_coach_tool.py track --habits 'exercise,reading' --status done
```

**检查点**：确认输出包含预期数据，无报错信息。

### Step 2：进度回顾

**目标**：回顾本月习惯完成情况

**为什么这一步重要**：核心处理阶段，将原始数据转化为有价值的输出。

**执行**：
```bash
python3 scripts/habit_coach_tool.py review --range month --show-streaks
```

**检查点**：确认生成结果格式正确，内容完整。

### Step 3：制定计划

**目标**：制定新的21天习惯计划

**为什么这一步重要**：最终输出阶段，将处理结果以可用的形式呈现。

**执行**：
```bash
python3 scripts/habit_coach_tool.py plan --habit '每天冥想10分钟' --duration 21d
```

**检查点**：确认最终输出符合预期格式和质量标准。

## 验证清单

- [ ] 依赖已安装：`pip install requests`
- [ ] Step 1 执行无报错，输出数据完整
- [ ] Step 2 处理结果符合预期格式
- [ ] Step 3 最终输出质量达标
- [ ] 无敏感信息泄露（API Key、密码等）

## 输出格式

```markdown
# 📊 习惯养成教练报告

**生成时间**: YYYY-MM-DD HH:MM

## 核心发现
1. [关键发现1]
2. [关键发现2]
3. [关键发现3]

## 数据概览
| 指标 | 数值 | 趋势 | 评级 |
|------|------|------|------|
| 指标A | XXX | ↑ | ⭐⭐⭐⭐ |
| 指标B | YYY | → | ⭐⭐⭐ |

## 详细分析
[基于实际数据的多维度分析内容]

## 行动建议
| 优先级 | 建议 | 预期效果 |
|--------|------|----------|
| 🔴 高 | [具体建议] | [量化预期] |
| 🟡 中 | [具体建议] | [量化预期] |
```

## 参考资料

### 原有链接
- [Atomic Habits框架](https://jamesclear.com/atomic-habits)

### GitHub
- [awesome-openclaw-usecases Habit Tracker](https://github.com/hesamsheikh/awesome-openclaw-usecases)

### Reddit
- [Reddit: AI习惯追踪与问责讨论](https://www.reddit.com/r/productivity/comments/ai_habit_tracker/)

## 注意事项

- 所有分析基于脚本获取的实际数据，**不编造数据**
- 数据缺失字段标注"数据不可用"而非猜测
- 建议结合人工判断使用，AI分析仅供参考
- 首次使用请先安装依赖：`pip install requests`
- 如遇到API限流，请适当增加请求间隔

FILE:references/habit_coach_guide.md
# 习惯养成教练 — 分析框架与参考指南

## 工具概述

**名称**: 习惯养成教练
**命令**: `track` (习惯打卡), `review` (进度回顾), `plan` (制定计划)
**依赖**: `pip install requests`

## 核心分析维度

- 个性化习惯计划制定与打卡追踪
- AI问责伙伴——鼓励/提醒/分析原因
- 习惯数据可视化与行为模式洞察

## 分析框架

### 维度一：数据采集与整理
- 确定数据来源和采集范围
- 清洗和标准化原始数据
- 建立基准对比指标

### 维度二：深度洞察与模式识别
- 多维度交叉分析
- 历史趋势识别和未来预测
- 异常值检测和根因分析

### 维度三：行动建议与决策支持
- 基于数据的具体可执行建议
- 优先级排序（高/中/低）
- 风险评估和应对预案

## 评分标准

| 评分 | 等级 | 描述 | 行动建议 |
|------|------|------|----------|
| 5分 | ⭐⭐⭐⭐⭐ 优秀 | 远超预期 | 立即采纳 |
| 4分 | ⭐⭐⭐⭐ 良好 | 超出预期 | 优先执行 |
| 3分 | ⭐⭐⭐ 一般 | 符合预期 | 可选执行 |
| 2分 | ⭐⭐ 偏弱 | 低于预期 | 需要改进 |
| 1分 | ⭐ 不足 | 明显不足 | 建议规避 |

## 输出模板

```markdown
# 习惯养成教练分析报告
## 核心发现
1. [发现1]
2. [发现2]

## 数据支撑
| 指标 | 数值 | 趋势 | 评级 |
|------|------|------|------|
| ... | ... | ... | ... |

## 行动建议
| 优先级 | 建议 | 依据 | 预期效果 |
|--------|------|------|----------|
| 🔴 高 | ... | ... | ... |
```

## 参考链接

### 原有链接
- [Atomic Habits框架](https://jamesclear.com/atomic-habits)

### GitHub
- [awesome-openclaw-usecases Habit Tracker](https://github.com/hesamsheikh/awesome-openclaw-usecases)

### Reddit
- [Reddit: AI习惯追踪与问责讨论](https://www.reddit.com/r/productivity/comments/ai_habit_tracker/)

## 使用提示

1. 本框架为习惯养成教练专用分析模板，可根据具体场景调整
2. 评分标准可按实际需求微调权重
3. 建议结合定量数据和定性判断综合分析

FILE:scripts/habit_coach_tool.py
#!/usr/bin/env python3
"""
习惯养成教练 — 工具脚本
功能: track, review, plan

用法:
    python3 habit_coach_tool.py track [args]    # 习惯打卡
    python3 habit_coach_tool.py review [args]    # 进度回顾
    python3 habit_coach_tool.py plan [args]    # 制定计划
"""

import sys, json, os
from datetime import datetime

DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "data")
REF_URLS = ["https://jamesclear.com/atomic-habits", "https://github.com/hesamsheikh/awesome-openclaw-usecases", "https://www.reddit.com/r/productivity/comments/ai_habit_tracker/"]

def ensure_data_dir():
    os.makedirs(DATA_DIR, exist_ok=True)

def load_data():
    data_file = os.path.join(DATA_DIR, "habit_coach_data.json")
    if os.path.exists(data_file):
        with open(data_file, "r", encoding="utf-8") as f:
            return json.load(f)
    return {"records": [], "created": datetime.now().isoformat(), "tool": "habit-coach"}

def save_data(data):
    ensure_data_dir()
    data_file = os.path.join(DATA_DIR, "habit_coach_data.json")
    with open(data_file, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)


def track(args):
    """习惯打卡"""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "track",
        "input": " ".join(args) if args else "",
        "status": "completed"
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "track",
        "message": "track完成",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3]
    }


def review(args):
    """进度回顾"""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "review",
        "input": " ".join(args) if args else "",
        "status": "completed"
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "review",
        "message": "review完成",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3]
    }


def plan(args):
    """制定计划"""
    data = load_data()
    record = {
        "timestamp": datetime.now().isoformat(),
        "command": "plan",
        "input": " ".join(args) if args else "",
        "status": "completed"
    }
    data["records"].append(record)
    save_data(data)
    return {
        "status": "success",
        "command": "plan",
        "message": "plan完成",
        "record": record,
        "total_records": len(data["records"]),
        "reference_urls": REF_URLS[:3]
    }


def main():
    cmds = ["track", "review", "plan"]
    if len(sys.argv) < 2 or sys.argv[1] not in cmds:
        print(json.dumps({
            "error": f"用法: habit_coach_tool.py <{','.join(cmds)}> [args]",
            "available_commands": {"track": "习惯打卡", "review": "进度回顾", "plan": "制定计划"},
            "tool": "habit-coach",
        }, ensure_ascii=False, indent=2))
        sys.exit(1)
    
    cmd = sys.argv[1]
    args = sys.argv[2:]
    
    result = globals()[cmd](args)
    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))

if __name__ == "__main__":
    main()

---
name: react-patterns
description: Deep React patterns workflow—component boundaries, composition, hooks rules, effects and data fetching, performance (memo, lists, suspense), testing, and accessibility. Use when structuring React apps, reviewing component design, or debugging re-renders.
---

# React Patterns (Deep Workflow)

Healthy React codebases emphasize **clear data flow**, **minimal effects**, and **predictable** rendering. Prefer **composition** over inheritance; treat **effects** as synchronization, not “do something after render” for everything.

## When to Offer This Workflow

**Trigger conditions:**

- Prop drilling vs context vs external stores; confusion on **server components** (Next) vs client
- **useEffect** spaghetti; stale closures; double-fetch
- Re-render performance; large lists; hydration issues

**Initial offer:**

Use **six stages**: (1) structure & boundaries, (2) state & data sources, (3) hooks discipline, (4) effects & events, (5) performance, (6) testing & a11y). Confirm **React** version and **framework** (plain CRA, Vite, Next App Router).

---

## Stage 1: Structure & Boundaries

**Goal:** **Colocate** state; split **presentational** vs **container** only when it clarifies—not by default.

### Practices

- **Compound components** for flexible APIs; avoid mega-props objects
- In Next App Router: default to Server Components; add `use client` at leaves

---

## Stage 2: State & Data Sources

**Goal:** **Local** state for UI; **server** state via React Query/SWR/Apollo as appropriate; avoid duplicating server entities in global stores without sync rules.

---

## Stage 3: Hooks Discipline

**Goal:** **Rules of Hooks** satisfied; custom hooks encapsulate reusable stateful logic with clear inputs/outputs.

### Practices

- Name hooks `useThing`; return stable APIs (objects memoized when needed)

---

## Stage 4: Effects & Events

**Goal:** Prefer **event handlers** for user-driven work; **useEffect** for sync with external systems (subscriptions, non-React widgets).

### Practices

- **Cleanup** subscriptions; **abort** fetches; list **effect** dependencies honestly
- Strict Mode double-invoke in dev—write effects idempotent

---

## Stage 5: Performance

**Goal:** Measure before `memo`; **virtualize** long lists; **code-split** routes.

### Practices

- `useCallback`/`useMemo` when profiling shows benefit—not by default
- **Concurrent** features and **Suspense** boundaries where supported

---

## Stage 6: Testing & Accessibility

**Goal:** **React Testing Library** user-centric queries; **focus** management and **labels** for forms.

---

## Final Review Checklist

- [ ] Component boundaries match data ownership
- [ ] Server vs client state strategy clear
- [ ] Hooks and effects used appropriately
- [ ] Performance optimizations evidence-based
- [ ] Tests and a11y basics covered for critical flows

## Tips for Effective Guidance

- **Derive** state when possible instead of storing redundant pieces.
- **URL** as state for shareable UI state when appropriate.
- Point to **state-management** skill for Redux/Zustand-scale decisions.

## Handling Deviations

- **Legacy class components:** same principles; hooks migration incremental.

---
name: rate-limiting
description: Deep rate limiting workflow—identifying actors and resources, choosing algorithms, distributed vs local limits, client UX (headers, retries), and abuse detection. Use when protecting APIs, gateways, or multi-tenant SaaS workloads.
---

# Rate Limiting (Deep Workflow)

Rate limits balance **fairness**, **availability**, and **abuse prevention**. Design explicitly: **who** is throttled, **what** resource is limited, and how clients should **back off**.

## When to Offer This Workflow

**Trigger conditions:**

- Protecting public APIs, auth endpoints, or expensive operations
- Multi-tenant “noisy neighbor” isolation
- Retry storms after incidents causing cascading 429/502

**Initial offer:**

Use **six stages**: (1) threat & fairness model, (2) dimensions & keys, (3) algorithms & config, (4) distributed enforcement, (5) client protocol & UX, (6) observability & tuning). Confirm enforcement layer (API gateway vs app middleware vs edge).

---

## Stage 1: Threat & Fairness Model

**Goal:** Distinguish legitimate bursts (batch jobs, mobile retries) from abuse; align limits with product tiers and SLAs.

**Exit condition:** Written policy: free vs paid limits, partner caps, burst allowances.

---

## Stage 2: Dimensions & Keys

**Goal:** Choose stable limit keys: authenticated user id > API key > IP (with shared-NAT caveats).

### Practices

- Per-tenant and global limits; separate expensive routes (exports, search)

---

## Stage 3: Algorithms & Config

**Goal:** Token bucket / leaky bucket for smooth bursts; sliding window for strict per-minute caps; consider **concurrency** limits separately from request rate.

---

## Stage 4: Distributed Enforcement

**Goal:** Central store (Redis, etc.) with atomic increments; handle multi-region (sticky routing vs shared counters); mind clock skew.

---

## Stage 5: Client Protocol & UX

**Goal:** Consistent **429** responses with **`Retry-After`**; document exponential backoff + jitter; optional `X-RateLimit-*` headers for transparency.

---

## Stage 6: Observability & Tuning

**Goal:** Metrics on throttles by route and actor class; alerts on abnormal deny spikes (attack vs misconfigured client).

---

## Final Review Checklist

- [ ] Policy matches tiers and fairness goals
- [ ] Limit keys stable and hard to spoof
- [ ] Algorithm matches burst vs sustained semantics
- [ ] Distributed correctness considered
- [ ] Client-facing 429 behavior documented
- [ ] Metrics and tuning loop defined

## Tips for Effective Guidance

- Coordinate with authentication—anonymous IP limits are coarse.
- Don’t throttle health checks in ways that break monitors.
- GraphQL: consider query **cost** / depth limits, not only HTTP count.
- WebSockets: separate connection caps from message rate limits.

## Handling Deviations

- **Edge/CDN:** limits may differ from origin—document both layers.

---
name: rag-pipelines
description: Deep RAG workflow—document ingestion, chunking, metadata, retrieval and reranking, grounding and citations, evaluation, and failure modes (hallucination, staleness). Use when building or debugging retrieval-augmented generation systems.
---

# RAG Pipelines (Deep Workflow)

RAG quality is dominated by **chunking**, **retrieval**, and **evaluation**—not the LLM alone. Treat the system as data engineering plus generation with explicit failure modes.

## When to Offer This Workflow

**Trigger conditions:**

- Building Q&A over internal docs, support assistants, or copilots
- Hallucinations, wrong citations, or stale answers
- New content types (PDF, HTML, code repositories)

**Initial offer:**

Use **six stages**: (1) task & success criteria, (2) ingestion & cleaning, (3) chunking & metadata, (4) retrieval & rerank, (5) generation & grounding, (6) evaluation & monitoring). Confirm embedding model and retrieval stack (vector DB, search engine, hybrid).

---

## Stage 1: Task & Success Criteria

**Goal:** Define what a “good” answer contains: required citations, length, tone, and when to refuse.

**Exit condition:** Written rubric with examples of acceptable vs unacceptable answers.

---

## Stage 2: Ingestion & Cleaning

**Goal:** Deterministic text extraction (strip boilerplate, handle PDF/OCR if needed); deduplicate documents; track source URL and `updated_at` for staleness.

### Practices

- Version pipelines when parsers change (re-embed job)

---

## Stage 3: Chunking & Metadata

**Goal:** Tune chunk size and overlap to query patterns—not one global token count for all content.

### Practices

- Attach metadata for ACL filtering (tenant, product area)
- Prefer structure-aware splits for docs (headings, sections)

---

## Stage 4: Retrieval & Rerank

**Goal:** Hybrid lexical + dense retrieval often beats vector-only for keyword-heavy queries.

### Practices

- Cross-encoder reranking on top-k for quality (watch latency)
- Query rewriting for multi-turn contexts

---

## Stage 5: Generation & Grounding

**Goal:** System prompts that require using only provided context; explicit “not found” behavior; optional citation format (snippet, doc id, link).

---

## Stage 6: Evaluation & Monitoring

**Goal:** Offline golden questions with expected supporting docs; online thumbs-down reasons; monitor retrieval hit rate, nDCG@k, and age of sources used.

---

## Final Review Checklist

- [ ] Rubric and refusal behavior defined
- [ ] Ingestion deterministic; dedupe and versioning
- [ ] Chunking and metadata match queries and ACLs
- [ ] Hybrid retrieval and rerank tuned with metrics
- [ ] Grounding and citation behavior enforced in prompts
- [ ] Offline eval plus production monitoring

## Tips for Effective Guidance

- Debug retrieval before blaming the LLM.
- Long chunks hurt precision; short chunks hurt context—sweep experiments.
- See also **vector-databases** and **llm-evaluation** skills for depth.

## Handling Deviations

- **Code RAG:** symbol- or AST-aware chunking often beats line-based splits.
- **High-stakes domains:** add human review gates and audit logs for sources cited.

---
name: python-packaging
description: Deep Python packaging workflow—pyproject metadata, dependencies and optional extras, build backends, wheels, versioning, publishing, and CI release hygiene. Use when building libraries or shipping CLI tools to PyPI or private indexes.
---

# Python Packaging (Deep Workflow)

Packaging connects source to installable artifacts. Prioritize **reproducible builds**, **accurate dependencies**, and **safe** automated releases.

## When to Offer This Workflow

**Trigger conditions:**

- New library or CLI; choosing among Poetry, Hatch, setuptools, uv, etc.
- Broken installs on some Python versions or platforms
- Publishing to PyPI or a private index from CI

**Initial offer:**

Use **six stages**: (1) project layout, (2) metadata & entry points, (3) dependencies, (4) build backend & wheels, (5) versioning & tags, (6) publish & CI). Confirm supported Python versions and target index.

---

## Stage 1: Project Layout

**Goal:** Prefer **`src/`** layout to avoid accidental imports from the repo root; one clear import package name.

**Exit condition:** `pip install .` in a clean venv imports the package correctly.

---

## Stage 2: Metadata & Entry Points

**Goal:** `pyproject.toml` with PEP 621 metadata; `[project.scripts]` or `[project.gui-scripts]` for CLIs.

### Practices

- Link README; specify license SPDX identifier
- Use classifiers for PyPI discoverability

---

## Stage 3: Dependencies

**Goal:** Separate runtime deps from optional extras (dev, docs, speedups); pin strategy differs for **libraries** vs **applications**.

### Libraries

- Avoid overly tight upper bounds unless necessary (avoid dependency hell for consumers)

### Applications

- Use lockfiles (pip-tools, uv, poetry lock) for reproducible deploys

---

## Stage 4: Build Backend & Wheels

**Goal:** Choose build backend (hatchling, setuptools, flit); emit **wheel** + **sdist** where appropriate.

### Native extensions

- Use **cibuildwheel** or similar for manylinux/macOS/windows matrices

---

## Stage 5: Versioning & Tags

**Goal:** Single source of truth for version (static in pyproject or dynamic from VCS); git tags match releases.

---

## Stage 6: Publish & CI

**Goal:** PyPI **trusted publishing** (OIDC) preferred over long-lived API tokens in secrets.

### Practices

- Test with TestPyPI when learning the flow
- Restrict token scope and enable 2FA on PyPI accounts

---

## Final Review Checklist

- [ ] src layout and imports verified in clean venv
- [ ] pyproject metadata complete; console scripts work
- [ ] Dependency policy documented (extras, bounds)
- [ ] Artifacts build for intended platforms
- [ ] Versioning aligned with tags; CI publishing secure

## Tips for Effective Guidance

- Add `py.typed` for typed libraries (PEP 561).
- Lazy-import heavy optional deps inside functions to keep CLI startup fast.
- Namespace packages are easy to misconfigure—prefer one clear top-level package name.

## Handling Deviations

- Monorepos: coordinate versions or use independent packages per folder with clear tooling.
- Docker-only apps: still package for testability; Dockerfile installs the wheel.

---
name: project-planning
description: Deep project planning workflow—goals and non-goals, work breakdown, dependencies, critical path, risks and buffers, milestones, and communication rhythm. Use when kicking off initiatives, replanning after slips, or coordinating cross-team delivery.
---

# Project Planning (Deep Workflow)

Plans are hypotheses—update them as facts arrive. Strong plans surface **dependencies early** and make **trade-offs** explicit (scope, date, quality).

## When to Offer This Workflow

**Trigger conditions:**

- Multi-team effort with a hard date or external dependency
- Timeline slip and need to re-baseline honestly
- Scope creep without prioritization conversation

**Initial offer:**

Use **six stages**: (1) frame outcome, (2) decompose work, (3) map dependencies, (4) schedule & buffers, (5) risks & mitigations, (6) operating rhythm. Confirm planning style (milestone-based, agile release train, hybrid).

---

## Stage 1: Frame Outcome

**Goal:** Problem statement, success criteria, **non-goals**, constraints (date, budget, compliance).

**Exit condition:** One-page charter stakeholders can align on.

---

## Stage 2: Decompose Work

**Goal:** Epics or WBS → trackable chunks—not necessarily micro-tasks unless execution needs it.

### Practices

- Prefer vertical slices (end-to-end thin features) over “all backend first” when possible

---

## Stage 3: Map Dependencies

**Goal:** External teams, vendors, legal, security, infra—on critical path.

### Practices

- Include lead time for reviews and procurement

**Exit condition:** Dependency table: item, owner, need-by date, status.

---

## Stage 4: Schedule & Buffers

**Goal:** Identify critical path; buffer **risky unknowns**, not every line uniformly.

### Practices

- Milestones with demo-ready acceptance criteria

---

## Stage 5: Risks & Mitigations

**Goal:** Top risks with likelihood/impact, owner, mitigation, and trigger for plan B.

---

## Stage 6: Operating Rhythm

**Goal:** Steady cadence: weekly tactical sync, steering at milestones, RAID log updates, decision log to avoid re-litigation.

---

## Final Review Checklist

- [ ] Charter: goals, non-goals, constraints
- [ ] Work breakdown with vertical slices where feasible
- [ ] Dependencies with owners and dates
- [ ] Schedule reflects critical path and buffers
- [ ] Risks tracked with mitigations
- [ ] Communication cadence agreed

## Tips for Effective Guidance

- Plans usually fail on hidden dependencies—make them visible.
- Fixed scope + fixed date + fixed quality: pick two explicitly.
- Agile still benefits from milestone intent for cross-company coordination.

## Handling Deviations

- Research-heavy work: timebox spikes before committing delivery dates.
- Small teams: minimum viable RAID + weekly priority still helps.

---
name: stakeholder-comms
description: Deep workflow for stakeholder communication—audience mapping, narrative structure, status with honesty, trade-off framing, asks, and follow-ups. Use when writing exec updates, cross-team notes, project summaries, or managing expectations under uncertainty.
---

# Stakeholder Communications (Deep Workflow)

Good stakeholder comms **reduce surprise**, **align decisions**, and **protect credibility**. The goal is not optimism—it is **clarity**, **appropriate detail**, and **explicit asks**.

## When to Offer This Workflow

**Trigger conditions:**

- Weekly exec update, steering committee, roadmap review
- Incident or delay disclosure
- Cross-functional dependency negotiation
- “Explain why we’re not building X”

**Initial offer:**

Use **five stages**: (1) audience & outcome, (2) facts & narrative, (3) risks & trade-offs, (4) ask & decision, (5) cadence & follow-up. Confirm **sensitivity** (can this be forwarded?) and **medium** (email, doc, live meeting).

---

## Stage 1: Audience & Outcome

**Goal:** Know **who reads**, **what they decide**, and **what success looks like**.

### Questions

1. Primary reader’s **role**: exec (time-poor), IC manager (detail-mixed), legal (risk), customer (trust)?
2. Desired **action**: approve, prioritize, unblock, stay informed?
3. **Political** context: past broken promises, skepticism, competing initiatives?

### Output

One sentence **purpose**: “After reading this, X should Y.”

**Exit condition:** **Level of detail** matches audience—no 10-page appendix for a 2-minute exec read unless requested.

---

## Stage 2: Facts & Narrative

**Goal:** **Truth first**, then a **coherent story**—not the reverse.

### Structure (flexible)

- **TL;DR** / **BLUF** (bottom line up front): status in one short block
- **What changed** since last update (delta-first)
- **Evidence**: metrics, dates, links—**bounded**; avoid data dumps in email body

### Tone

- **Neutral and specific**: “slipped 1 week due to dependency X” beats “we’re working hard”
- **No passive voice hiding ownership**: who does what by when

**Exit condition:** Reader can answer **where we are**, **why**, **what’s next** without a meeting.

---

## Stage 3: Risks & Trade-offs

**Goal:** Surface **bad news early** with **mitigation**, not panic.

### Framework

- **Risk**: description, **likelihood/impact** (even qualitative), **mitigation**, **trigger** to escalate
- **Trade-offs**: Option A vs B with **criteria** (time, cost, quality, security)

### Trust

- Admitting uncertainty: “We don’t know yet; we will know by DATE via METHOD”

**Exit condition:** No **hidden** dependency or date slip—if unknown, **date the unknown**.

---

## Stage 4: Ask & Decision

**Goal:** If a decision is needed, make it **easy to make**.

### Practices

- **Single explicit ask**: “Please approve budget for…” / “Choose path A or B by Friday”
- **Options** with recommendation and **reversibility**
- **Deadline** and **default** if no response (when appropriate and ethical)

**Exit condition:** Stakeholder knows **exactly** what to say yes/no to.

---

## Stage 5: Cadence & Follow-Up

**Goal:** Comms **compound**—track commitments and close loops.

### Practices

- **Action table**: owner, deliverable, date—carry forward until done
- **Next update** date; **what will change** by then
- After meetings: **notes** with decisions distributed within 24h when stakes high

### Escalation

- Clear **path** when blocked: who to ping, what info they need

---

## Final Review Checklist

- [ ] Audience and desired outcome explicit
- [ ] BLUF + delta + evidence (proportionate)
- [ ] Risks and trade-offs visible; ownership clear
- [ ] Ask/decision unambiguous
- [ ] Follow-up mechanism exists

## Tips for Effective Guidance

- **Executives**: lead with **business impact** and **decision**; appendix for nerds.
- **Peers**: more **technical** detail and **interface contracts**.
- Never **surprise** your own manager in a larger forum—pre-brief.

## Handling Deviations

- **Highly political**: focus on **facts**, **options**, **documented** agreements; avoid chat-room venting in writing.
- **Cultural**: adapt directness; clarity stays, **bluntness** may soften.

---
name: ssr-ssg
description: Deep workflow for SSR, SSG, ISR, and hybrid rendering—choosing modes per route, data freshness, caching, streaming, hydration, SEO, and operational trade-offs (Next.js, Nuxt, Remix, etc.). Use when tuning web apps for performance, correctness, and crawlability.
---

# SSR / SSG / Hybrid Rendering (Deep Workflow)

Rendering is an **architecture decision**, not a framework toggle. Guide users to map **freshness**, **personalization**, **cost**, and **complexity** per route—avoid “SSR everything” or “static everything” by default.

## When to Offer This Workflow

**Trigger conditions:**

- Choosing rendering strategy for marketing vs app shell vs dashboards
- SEO + auth + dynamic data conflicts
- Slow TTFB, stale content, or expensive server work per request
- Hydration bugs, double data fetch, or client/server environment mismatch

**Initial offer:**

Use **six stages**: (1) route & data classification, (2) choose rendering mode(s), (3) data loading & cache layers, (4) streaming & partial SSR, (5) hydration & client boundaries, (6) validate (SEO, perf, ops). Confirm **framework** and **hosting** (Node server, serverless, edge).

---

## Stage 1: Route & Data Classification

**Goal:** Each **route** has clear **freshness**, **auth**, and **personalization** needs.

### Dimensions

- **Public vs authenticated**: can HTML be shared or per-user?
- **Update frequency**: static marketing, hourly blog, real-time inventory
- **Source of truth**: CMS, DB, API with rate limits, edge KV

### Output

A **matrix**: route pattern → public/private → max staleness acceptable → personalization level.

**Exit condition:** No ambiguous “dynamic page” without stating **what changes** and **how often**.

---

## Stage 2: Choose Rendering Mode(s)

**Goal:** Pick **SSG**, **SSR**, **ISR/ondemand revalidate**, **CSR with SSR shell**, or **edge**—per route.

### Heuristics

- **SSG / prerender**: stable content, best TTFB/CDN cache, great SEO—watch **rebuild/revalidate** story
- **SSR**: must reflect **request-time** data (A/B, geo, auth gating) or **strict freshness**
- **Client-heavy**: acceptable for **post-auth** app surfaces if SEO not needed
- **Hybrid**: static shell + client islands; or **static generation** with **server components** for parts (framework-specific)

### Trade-offs

- SSR **cost** and **latency** vs SSG **staleness**
- **Edge** rendering: geography and limits (CPU, Node APIs)

**Exit condition:** Documented **per-route** strategy with **rationale**.

---

## Stage 3: Data Loading & Cache Layers

**Goal:** **One coherent story** for where data is fetched and how it is cached (CDN, full-page, data cache, edge).

### Practices

- **Cache-Control** / surrogate keys / tag-based invalidation—align with framework primitives (e.g., `revalidate`, `fetch` cache)
- **Deduplicate** requests between server and client where frameworks allow
- **Avoid** accidental **private data in shared cache**—vary by cookie/auth correctly or disable cache

### Stale-While-Revalidate

- Great for **mostly fresh**—document **user-visible staleness** acceptance

**Exit condition:** Data flow diagram: origin → edge → browser; **invalidation** owner identified.

---

## Stage 4: Streaming & Partial SSR

**Goal:** Improve **perceived performance** with **suspense/streaming** where supported.

### Guidance

- Defer **slow** fragments; show **skeletons** with accessible semantics
- **Ordering**: ensure critical **LCP** resources not blocked by deferred junk
- **Headers**: understand **chunked** response implications for intermediaries

**Exit condition:** Slow dependencies **isolated**; UX fallbacks defined.

---

## Stage 5: Hydration & Client Boundaries

**Goal:** **Correct** interactive UI without **double work** or **mismatches**.

### Checklist

- **Server/client** component or module boundaries (framework-specific)
- **useEffect** vs server fetch duplication—**waterfalls**
- **Environment**: no `window` on server; no **secret** APIs in client bundles
- **Hydration mismatch**: locale, random IDs, time—**suppress** or **serialize state**

**Exit condition:** Known **interactive islands** listed; mismatch risks mitigated.

---

## Stage 6: Validate (SEO, Performance, Ops)

**Goal:** Rendering choices **show up** correctly in search, metrics, and logs.

### SEO

- **View source** / rendered HTML for critical content; **meta** and **canonical** per mode
- **Auth**: soft paywalls—decide what crawlers see ethically and technically

### Performance

- **TTFB** vs **FCP/LCP**; **server time** vs **edge cache hit**
- **RUM** segmented by route and cache hit

### Ops

- **Cold starts** on serverless SSR; **concurrency** limits; **regional** failover

---

## Final Review Checklist

- [ ] Per-route rendering choice documented with freshness/personalization
- [ ] Caching and invalidation story is explicit and safe for auth
- [ ] Streaming/skeletons don’t harm LCP or a11y
- [ ] Hydration and env boundaries verified
- [ ] SEO and RUM validation for top templates

## Tips for Effective Guidance

- Name **staleness** in seconds/minutes—“real-time” is rarely real-time.
- When user uses **Next.js**, tie advice to **App Router** vs **Pages** semantics explicitly if known.
- Warn: **edge** ≠ full Node—**API surface** differs.

## Handling Deviations

- **SPA-only**: focus on **meta** for landing routes and **prerender** for marketing if added later.
- **No server**: SSG + client or **external** prerender service—be honest about limits.

---
name: sre-practices
description: Deep SRE workflow—SLOs/SLIs, error budgets, alerting, toil reduction, incident readiness, capacity, and balancing reliability with delivery. Use when improving production culture, defining service reliability targets, or reducing on-call pain.
---

# SRE Practices (Deep Workflow)

SRE is not “ops with a fancy title”—it is **engineering reliability** with **explicit trade-offs** between velocity and stability, measured with **SLOs** and managed through **error budgets** and **toil budgets**.

## When to Offer This Workflow

**Trigger conditions:**

- Defining or revisiting **SLOs**; too many pages or too few alerts
- “We need five nines” without user-visible meaning
- High **toil**: manual deploys, ticket-driven scaling, runbooks that never shrink
- Post-incident push for “more reliability” without cost discussion

**Initial offer:**

Walk through **six stages**: (1) user journeys & SLIs, (2) SLO targets & windows, (3) error budgets & policy, (4) alerting & on-call, (5) toil & automation, (6) continuous improvement. Confirm **service tiering** and **business criticality**.

---

## Stage 1: User Journeys & SLIs

**Goal:** Measure **what users actually experience**, not only server uptime.

### Activities

- List **critical journeys**: signup, pay, search, API sync, etc.
- For each, pick **SLI types**: availability, latency, freshness, correctness (where measurable)
- Define **SLI implementation**: e.g., “successful HTTP 2xx from LB / all requests excluding health checks” vs deeper **synthetic** probes

### Good SLIs

- **Specific**, **measurable**, **aligned** with pain—avoid vanity metrics

**Exit condition:** SLI definitions **documented** with data sources (metrics, logs, probes).

---

## Stage 2: SLO Targets & Windows

**Goal:** Set **achievable** targets with **explicit consequences**.

### Process

- Choose **window**: rolling 30d common; align with release cadence
- Set **target** (e.g., 99.9% availability) from **error budget** math: allowed downtime per month
- **Tier** services: not everything needs 99.99%

### Realism

- Account for **dependencies** you don’t control (public cloud, third-party APIs)—SLO cannot exceed dependency SLO unless architecture isolates failures.

**Exit condition:** Published **SLO document** per service or journey with **measurement method**.

---

## Stage 3: Error Budget Policy

**Goal:** Decide **how to spend** budget—feature velocity vs reliability work.

### Policy Examples

- Budget healthy → **ship** aggressively; budget low → **freeze** risky changes, focus on reliability
- **Exceptions** process: who can override, with what review

### Communication

- Product/engineering **shared ownership** of budget—not “SRE says no” in the dark

**Exit condition:** Written **policy**: what happens when budget burns at 25/50/100%.

---

## Stage 4: Alerting & On-Call

**Goal:** Pages are **symptom-based**, **actionable**, **low noise**.

### Principles

- Alert on **user pain** or **imminent SLO threat**, not every blip
- **Severity** maps to response: SEV1 customer-wide vs warning
- **Runbooks** linked; **ownership** clear

### On-Call Health

- **Limit pages** per engineer per week; track **toil hours**
- **Post-incident** follow-through to reduce repeat pages

**Exit condition:** Alert inventory reviewed; **tuning** backlog for noisy alerts.

---

## Stage 5: Toil & Automation

**Goal:** Reduce **manual, repetitive, automatable** work with **measurable** toil budgets.

### Identify Toil

- Frequent tickets, manual scaling, click-ops deploys, data fixes without guardrails

### Remediate

- **Eliminate** > **automate** > **document**—in that preference order when safe
- **Self-service** platforms with guardrails beat hero scripts

**Exit condition:** Toil reduction **roadmap** with owners; ideally **50%** toil cap aspiration per team norm (Google SRE guideline—adapt to org).

---

## Stage 6: Continuous Improvement

**Goal:** Reliability work is **prioritized** like features.

### Loops

- **Incident** → action items with tracking
- **Game days** / failure injection where mature
- **Quarterly** SLO review—targets drift with product changes

---

## Final Review Checklist

- [ ] SLIs tied to user-visible outcomes
- [ ] SLO targets realistic vs dependencies
- [ ] Error budget policy agreed with product
- [ ] Alerts actionable; noise tracked
- [ ] Toil identified with automation path

## Tips for Effective Guidance

- Translate **99.9%** to **minutes of downtime per month**—makes trade-offs concrete.
- Never promise **zero incidents**; promise **learning** and **measurable** improvement.
- Separate **SLI** (measurement) from **SLO** (target) from **SLA** (contract)—terms get confused.

## Handling Deviations

- **Early startup**: start with **basic monitoring + incident reviews** before full SLO program.
- **No SRE role**: practices still apply—relabel “production excellence” if needed.

---
name: sql-optimization
description: Deep SQL performance workflow—symptom framing, execution plans, indexing strategy, query rewrite, locking/transaction behavior, statistics, partitioning, and verification. Use when queries time out, DB CPU spikes, or migrations change access patterns.
---

# SQL Optimization (Deep Workflow)

Optimization without measurement is guesswork. Structure the work as **observe → explain (plan) → change → verify**, with explicit attention to **correctness**, **locks**, and **write amplification** from indexes.

## When to Offer This Workflow

**Trigger conditions:**

- Slow queries, growing P95/P99, replication lag, lock waits
- ORM-generated SQL surprises; N+1 at DB layer
- Index explosion, bloat, or “we added indexes everywhere”

**Initial offer:**

Use **six stages**: (1) frame the problem, (2) reproduce & measure, (3) read execution plans, (4) schema & indexes, (5) query & transaction tuning, (6) verify & guardrail. Confirm **engine** (PostgreSQL, MySQL, SQL Server, etc.) and **environment** (prod-like data volume).

---

## Stage 1: Frame the Problem

**Goal:** Define **SLO**, **scope**, and **non-goals**.

### Questions

1. Which **queries** or **endpoints** are slow? User-facing vs batch?
2. **Regression**—did deploy, data volume, or stats change?
3. **Isolation level** and **consistency** requirements—can we read replicas?
4. **Write risk**: is this table write-heavy? Index cost?

**Exit condition:** One-line **problem statement** with metric (e.g., “p95 2.4s on `/reports` at 10k RPS”).

---

## Stage 2: Reproduce & Measure

**Goal:** **Stable repro** with representative **cardinality** and **parameters**.

### Actions

- Capture **exact SQL**, parameters, and **frequency**
- Use **EXPLAIN (ANALYZE, BUFFERS)** or equivalent—engine-specific
- Check **buffer cache** effects: cold vs warm cache; run twice when needed
- Compare **prod stats** vs staging—row counts, histograms

### Pitfalls

- Optimizing on empty dev DB
- Different **parameter sniffing** values changing plan choice

**Exit condition:** Baseline numbers + **plan hash** or saved plan for A/B.

---

## Stage 3: Read Execution Plans

**Goal:** Name the **dominant cost**: seq scan, bad join order, sort, hash spill, nested loop explosion.

### Interpret (adapt to engine)

- **Seq scan** on large tables—filter selectivity? missing index? stats?
- **Index scan** vs **bitmap** vs **index only**—covering indexes trade-offs
- **Joins**: wrong order, missing stats, outdated NDV
- **Sort/hash** spills to disk—work_mem / memory grants
- **Locks**: `FOR UPDATE`, long transactions, hot row updates

**Exit condition:** Hypothesis tied to **plan node(s)**, not generic “add index.”

---

## Stage 4: Schema & Indexes

**Goal:** **Right indexes** for read paths without destroying writes.

### Strategy

- **Composite index column order**: equality → range; avoid redundant indexes
- **Partial indexes** for hot subsets
- **Covering** indexes vs table bloat—measure write cost
- **Foreign keys** and **constraints** affecting plans
- **Statistics**: `ANALYZE`, extended stats, histograms—when stale stats lie

### Advanced (when relevant)

- **Partitioning** for prune + maintenance
- **Materialized views** / pre-aggregation for heavy reports

**Exit condition:** DDL proposal with **rationale** and **rollback** (drop index concurrently if supported).

---

## Stage 5: Query & Transaction Tuning

**Goal:** Sometimes the fix is **SQL rewrite**, not hardware.

### Techniques

- Reduce **rows touched** early (CTEs vs inline—engine-dependent)
- **Pagination** without OFFSET on huge pages (keyset)
- **Batch** vs row-by-row; **UNION ALL** vs OR
- **N+1**: batch queries, joins, data loader patterns
- **Transactions**: shorten locks; avoid unnecessary `SELECT FOR UPDATE`
- **ORM**: eager vs lazy loading discipline

**Exit condition:** New plan shows lower cost / measured latency; **lock time** acceptable.

---

## Stage 6: Verify & Guardrail

**Goal:** Improvement **holds** under load and doesn’t regress neighbors.

### Verify

- Re-run **EXPLAIN ANALYZE** with production-like parameters
- Load test or shadow traffic if available
- **Monitor**: buffer hit ratio, index bloat, replication lag

### Guardrails

- **Query timeouts** and **statement_timeout** where safe
- **Alerts** on sequential scans on large tables if observability supports

---

## Final Review Checklist

- [ ] Baseline and target metrics documented
- [ ] Plan-based root cause, not guesswork
- [ ] Index/DDL changes justified vs write load
- [ ] Transaction/lock behavior considered
- [ ] Verification on realistic data and load

## Tips for Effective Guidance

- Always mention **parameter sniffing** and **stale statistics** as frequent culprits.
- Warn when **adding indexes** on very write-heavy tables without measuring bloat.
- Prefer **keyset pagination** education for large lists.

## Handling Deviations

- **No EXPLAIN access**: infer from symptoms + ORM logs + index list; recommend safe staging repro.
- **Vendor DB**: name that **hints** and features differ—avoid PostgreSQL-only advice on SQL Server without caveat.

---
name: backup-recovery
description: "Backups, RPO/RTO, restores, and drills. Use when designing DR or testing restores."
---

# Backup Recovery Skill

This skill provides structured guidance for **Backup Recovery** work. Act as an active guide: confirm triggers, propose the stages below, and adapt if the user wants a lighter pass.

## When to Offer This Workflow

**Trigger conditions:**
- User mentions **backup recovery** or closely related work
- They want a structured workflow rather than ad-hoc tips
- They are preparing a review, rollout, or stakeholder communication

**Initial offer:**
Explain the four stages briefly and ask whether to follow this workflow or work freeform. If they decline, continue in their preferred style.

## Workflow Stages

### Stage 1: Clarify context & goals

Anchor on **RPO/RTO targets**. Ask what success looks like, constraints, and what must not break. Capture unknowns early.

### Stage 2: Design or plan the approach

Translate goals into a concrete plan around **backup testing**. Compare alternatives and explicit trade-offs; avoid implicit assumptions.

### Stage 3: Implement, validate, and harden

Execute with verification loops tied to **restore drills**. Prefer small steps, measurable checks, and rollback points where risk is high.

### Stage 4: Operate, communicate, and iterate

Close the loop with **runbooks and ownership**: monitoring, documentation, stakeholder updates, and lessons learned for the next cycle.

## Checklist Before Completion

- Goals and constraints are explicit for **Backup Recovery Skill**
- Risks and trade-offs are stated, not hand-waved
- Verification steps match the change’s impact (tests, canary, peer review)
- Operational follow-through is covered (monitoring, docs, owners)

## Tips for Effective Guidance

- Be procedural: stage-by-stage, with clear exit criteria
- Ask for missing context (environment, scale, deadlines) before prescribing
- Prefer checklists and concrete examples over generic platitudes
- If the user declines the workflow, switch to freeform help without lecturing

## Handling Deviations

- If the user wants to skip a stage: confirm and continue with what they need.
- If context is missing: ask targeted questions before strong recommendations.
- Prefer concrete examples, trade-offs, and verification steps over generic advice.

## Quality Bar

- Each recommendation should be **actionable** (what to do next).
- Call out **failure modes** relevant to Backup Recovery (security, scale, UX, or ops).
- Keep tone direct and respectful of the user’s time.

---
name: arxiv-query
description: Search and summarize papers from ArXiv. Use when the user asks for the latest research, specific topics on ArXiv, or a daily summary of AI papers.
---

# ArXiv Query

This skill interacts with the ArXiv API to find and summarize the latest research papers.

## Capabilities

- **Search**: Find papers by keyword, author, or category.
- **Summarize**: Fetch the abstract and provide a concise summary.
- **Save to Memory**: Automatically record summarized papers to `memory/RESEARCH_LOG.md` for long-term tracking.
- **Deep Dive**: Use `web_fetch` on the PDF link to extract more details if requested.

## Workflow

1. Use `scripts/search_arxiv.sh "<query>"` to get the XML results.
2. Parse the XML (look for `<entry>`, `<title>`, `<summary>`, and `<link title="pdf">`).
3. Present the findings to the user.
4. **MANDATORY**: Append the title, authors, date, and summary of any paper discussed to `memory/RESEARCH_LOG.md`. Use the format:
   ```markdown
   ### [YYYY-MM-DD] TITLE_OF_PAPER
   - **Authors**: Author List
   - **Link**: ArXiv Link
   - **Summary**: Brief summary of the paper and its relevance.
   ```

## Examples

- "Busca los últimos papers sobre LLM reasoning en ArXiv."
- "Dime de qué trata el paper con ID 2512.08769."
- "Hazme un resumen de las novedades de hoy en ArXiv sobre agentes."

## Resources

- `scripts/search_arxiv.sh`: Direct API access script.

FILE:scripts/search_arxiv.sh
#!/usr/bin/env bash
# scripts/search_arxiv.sh
QUERY=$1
COUNT=-5
# Use curl to query ArXiv API
curl -sL "https://export.arxiv.org/api/query?search_query=all:$QUERY&start=0&max_results=$COUNT&sortBy=submittedDate&sortOrder=descending"

---
name: doc-coauthoring
description: Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
---

# Doc Co-Authoring Workflow

This skill provides a structured workflow for guiding users through collaborative document creation. Act as an active guide, walking users through three stages: Context Gathering, Refinement & Structure, and Reader Testing.

## When to Offer This Workflow

**Trigger conditions:**
- User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
- User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
- User seems to be starting a substantial writing task

**Initial offer:**
Offer the user a structured workflow for co-authoring the document. Explain the three stages:

1. **Context Gathering**: User provides all relevant context while Claude asks clarifying questions
2. **Refinement & Structure**: Iteratively build each section through brainstorming and editing
3. **Reader Testing**: Test the doc with a fresh Claude (no context) to catch blind spots before others read it

Explain that this approach helps ensure the doc works well when others read it (including when they paste it into Claude). Ask if they want to try this workflow or prefer to work freeform.

If user declines, work freeform. If user accepts, proceed to Stage 1.

## Stage 1: Context Gathering

**Goal:** Close the gap between what the user knows and what Claude knows, enabling smart guidance later.

### Initial Questions

Start by asking the user for meta-context about the document:

1. What type of document is this? (e.g., technical spec, decision doc, proposal)
2. Who's the primary audience?
3. What's the desired impact when someone reads this?
4. Is there a template or specific format to follow?
5. Any other constraints or context to know?

Inform them they can answer in shorthand or dump information however works best for them.

**If user provides a template or mentions a doc type:**
- Ask if they have a template document to share
- If they provide a link to a shared document, use the appropriate integration to fetch it
- If they provide a file, read it

**If user mentions editing an existing shared document:**
- Use the appropriate integration to read the current state
- Check for images without alt-text
- If images exist without alt-text, explain that when others use Claude to understand the doc, Claude won't be able to see them. Ask if they want alt-text generated. If so, request they paste each image into chat for descriptive alt-text generation.

### Info Dumping

Once initial questions are answered, encourage the user to dump all the context they have. Request information such as:
- Background on the project/problem
- Related team discussions or shared documents
- Why alternative solutions aren't being used
- Organizational context (team dynamics, past incidents, politics)
- Timeline pressures or constraints
- Technical architecture or dependencies
- Stakeholder concerns

Advise them not to worry about organizing it - just get it all out. Offer multiple ways to provide context:
- Info dump stream-of-consciousness
- Point to team channels or threads to read
- Link to shared documents

**If integrations are available** (e.g., Slack, Teams, Google Drive, SharePoint, or other MCP servers), mention that these can be used to pull in context directly.

**If no integrations are detected and in Claude.ai or Claude app:** Suggest they can enable connectors in their Claude settings to allow pulling context from messaging apps and document storage directly.

Inform them clarifying questions will be asked once they've done their initial dump.

**During context gathering:**

- If user mentions team channels or shared documents:
  - If integrations available: Inform them the content will be read now, then use the appropriate integration
  - If integrations not available: Explain lack of access. Suggest they enable connectors in Claude settings, or paste the relevant content directly.

- If user mentions entities/projects that are unknown:
  - Ask if connected tools should be searched to learn more
  - Wait for user confirmation before searching

- As user provides context, track what's being learned and what's still unclear

**Asking clarifying questions:**

When user signals they've done their initial dump (or after substantial context provided), ask clarifying questions to ensure understanding:

Generate 5-10 numbered questions based on gaps in the context.

Inform them they can use shorthand to answer (e.g., "1: yes, 2: see #channel, 3: no because backwards compat"), link to more docs, point to channels to read, or just keep info-dumping. Whatever's most efficient for them.

**Exit condition:**
Sufficient context has been gathered when questions show understanding - when edge cases and trade-offs can be asked about without needing basics explained.

**Transition:**
Ask if there's any more context they want to provide at this stage, or if it's time to move on to drafting the document.

If user wants to add more, let them. When ready, proceed to Stage 2.

## Stage 2: Refinement & Structure

**Goal:** Build the document section by section through brainstorming, curation, and iterative refinement.

**Instructions to user:**
Explain that the document will be built section by section. For each section:
1. Clarifying questions will be asked about what to include
2. 5-20 options will be brainstormed
3. User will indicate what to keep/remove/combine
4. The section will be drafted
5. It will be refined through surgical edits

Start with whichever section has the most unknowns (usually the core decision/proposal), then work through the rest.

**Section ordering:**

If the document structure is clear:
Ask which section they'd like to start with.

Suggest starting with whichever section has the most unknowns. For decision docs, that's usually the core proposal. For specs, it's typically the technical approach. Summary sections are best left for last.

If user doesn't know what sections they need:
Based on the type of document and template, suggest 3-5 sections appropriate for the doc type.

Ask if this structure works, or if they want to adjust it.

**Once structure is agreed:**

Create the initial document structure with placeholder text for all sections.

**If access to artifacts is available:**
Use `create_file` to create an artifact. This gives both Claude and the user a scaffold to work from.

Inform them that the initial structure with placeholders for all sections will be created.

Create artifact with all section headers and brief placeholder text like "[To be written]" or "[Content here]".

Provide the scaffold link and indicate it's time to fill in each section.

**If no access to artifacts:**
Create a markdown file in the working directory. Name it appropriately (e.g., `decision-doc.md`, `technical-spec.md`).

Inform them that the initial structure with placeholders for all sections will be created.

Create file with all section headers and placeholder text.

Confirm the filename has been created and indicate it's time to fill in each section.

**For each section:**

### Step 1: Clarifying Questions

Announce work will begin on the [SECTION NAME] section. Ask 5-10 clarifying questions about what should be included:

Generate 5-10 specific questions based on context and section purpose.

Inform them they can answer in shorthand or just indicate what's important to cover.

### Step 2: Brainstorming

For the [SECTION NAME] section, brainstorm [5-20] things that might be included, depending on the section's complexity. Look for:
- Context shared that might have been forgotten
- Angles or considerations not yet mentioned

Generate 5-20 numbered options based on section complexity. At the end, offer to brainstorm more if they want additional options.

### Step 3: Curation

Ask which points should be kept, removed, or combined. Request brief justifications to help learn priorities for the next sections.

Provide examples:
- "Keep 1,4,7,9"
- "Remove 3 (duplicates 1)"
- "Remove 6 (audience already knows this)"
- "Combine 11 and 12"

**If user gives freeform feedback** (e.g., "looks good" or "I like most of it but...") instead of numbered selections, extract their preferences and proceed. Parse what they want kept/removed/changed and apply it.

### Step 4: Gap Check

Based on what they've selected, ask if there's anything important missing for the [SECTION NAME] section.

### Step 5: Drafting

Use `str_replace` to replace the placeholder text for this section with the actual drafted content.

Announce the [SECTION NAME] section will be drafted now based on what they've selected.

**If using artifacts:**
After drafting, provide a link to the artifact.

Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.

**If using a file (no artifacts):**
After drafting, confirm completion.

Inform them the [SECTION NAME] section has been drafted in [filename]. Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.

**Key instruction for user (include when drafting the first section):**
Provide a note: Instead of editing the doc directly, ask them to indicate what to change. This helps learning of their style for future sections. For example: "Remove the X bullet - already covered by Y" or "Make the third paragraph more concise".

### Step 6: Iterative Refinement

As user provides feedback:
- Use `str_replace` to make edits (never reprint the whole doc)
- **If using artifacts:** Provide link to artifact after each edit
- **If using files:** Just confirm edits are complete
- If user edits doc directly and asks to read it: mentally note the changes they made and keep them in mind for future sections (this shows their preferences)

**Continue iterating** until user is satisfied with the section.

### Quality Checking

After 3 consecutive iterations with no substantial changes, ask if anything can be removed without losing important information.

When section is done, confirm [SECTION NAME] is complete. Ask if ready to move to the next section.

**Repeat for all sections.**

### Near Completion

As approaching completion (80%+ of sections done), announce intention to re-read the entire document and check for:
- Flow and consistency across sections
- Redundancy or contradictions
- Anything that feels like "slop" or generic filler
- Whether every sentence carries weight

Read entire document and provide feedback.

**When all sections are drafted and refined:**
Announce all sections are drafted. Indicate intention to review the complete document one more time.

Review for overall coherence, flow, completeness.

Provide any final suggestions.

Ask if ready to move to Reader Testing, or if they want to refine anything else.

## Stage 3: Reader Testing

**Goal:** Test the document with a fresh Claude (no context bleed) to verify it works for readers.

**Instructions to user:**
Explain that testing will now occur to see if the document actually works for readers. This catches blind spots - things that make sense to the authors but might confuse others.

### Testing Approach

**If access to sub-agents is available (e.g., in Claude Code):**

Perform the testing directly without user involvement.

### Step 1: Predict Reader Questions

Announce intention to predict what questions readers might ask when trying to discover this document.

Generate 5-10 questions that readers would realistically ask.

### Step 2: Test with Sub-Agent

Announce that these questions will be tested with a fresh Claude instance (no context from this conversation).

For each question, invoke a sub-agent with just the document content and the question.

Summarize what Reader Claude got right/wrong for each question.

### Step 3: Run Additional Checks

Announce additional checks will be performed.

Invoke sub-agent to check for ambiguity, false assumptions, contradictions.

Summarize any issues found.

### Step 4: Report and Fix

If issues found:
Report that Reader Claude struggled with specific issues.

List the specific issues.

Indicate intention to fix these gaps.

Loop back to refinement for problematic sections.

---

**If no access to sub-agents (e.g., claude.ai web interface):**

The user will need to do the testing manually.

### Step 1: Predict Reader Questions

Ask what questions people might ask when trying to discover this document. What would they type into Claude.ai?

Generate 5-10 questions that readers would realistically ask.

### Step 2: Setup Testing

Provide testing instructions:
1. Open a fresh Claude conversation: https://claude.ai
2. Paste or share the document content (if using a shared doc platform with connectors enabled, provide the link)
3. Ask Reader Claude the generated questions

For each question, instruct Reader Claude to provide:
- The answer
- Whether anything was ambiguous or unclear
- What knowledge/context the doc assumes is already known

Check if Reader Claude gives correct answers or misinterprets anything.

### Step 3: Additional Checks

Also ask Reader Claude:
- "What in this doc might be ambiguous or unclear to readers?"
- "What knowledge or context does this doc assume readers already have?"
- "Are there any internal contradictions or inconsistencies?"

### Step 4: Iterate Based on Results

Ask what Reader Claude got wrong or struggled with. Indicate intention to fix those gaps.

Loop back to refinement for any problematic sections.

---

### Exit Condition (Both Approaches)

When Reader Claude consistently answers questions correctly and doesn't surface new gaps or ambiguities, the doc is ready.

## Final Review

When Reader Testing passes:
Announce the doc has passed Reader Claude testing. Before completion:

1. Recommend they do a final read-through themselves - they own this document and are responsible for its quality
2. Suggest double-checking any facts, links, or technical details
3. Ask them to verify it achieves the impact they wanted

Ask if they want one more review, or if the work is done.

**If user wants final review, provide it. Otherwise:**
Announce document completion. Provide a few final tips:
- Consider linking this conversation in an appendix so readers can see how the doc was developed
- Use appendices to provide depth without bloating the main doc
- Update the doc as feedback is received from real readers

## Tips for Effective Guidance

**Tone:**
- Be direct and procedural
- Explain rationale briefly when it affects user behavior
- Don't try to "sell" the approach - just execute it

**Handling Deviations:**
- If user wants to skip a stage: Ask if they want to skip this and write freeform
- If user seems frustrated: Acknowledge this is taking longer than expected. Suggest ways to move faster
- Always give user agency to adjust the process

**Context Management:**
- Throughout, if context is missing on something mentioned, proactively ask
- Don't let gaps accumulate - address them as they come up

**Artifact Management:**
- Use `create_file` for drafting full sections
- Use `str_replace` for all edits
- Provide artifact link after every change
- Never use artifacts for brainstorming lists - that's just conversation

**Quality over Speed:**
- Don't rush through stages
- Each iteration should make meaningful improvements
- The goal is a document that actually works for readers

---
name: "网红砂锅"
description: "提供关于网红砂锅的推荐清单、打卡路线与指南。用户搜索网红砂锅或规划相关出行时调用。"
---

# 网红砂锅

## 适用场景
- 用户搜索网红砂锅或规划相关出行时调用
- 需要获取网红砂锅的推荐清单、打卡路线与简要指南

## 使用方式
- 输入城市或区域，可筛选主题、预算、时段
- 支持返回快速路线建议与人气分级

## 返回内容
- 推荐清单：名称/亮点/地址/时间/人气
- 路线草案：交通方式/用时/顺序/避坑提示
- 注意事项：预约/排队时长/最佳时段/费用范围

## 示例请求
- “成都 网红砂锅 一日打卡路线”
- “上海适合情侣的 网红砂锅 TOP10”

## 更新频率
- 每周迭代，结合新热度与口碑反馈

## 注意事项
- 高峰期排队较久，建议提前预约或错峰
- 部分项目有拍摄限制或最低消费，按现场规则执行

## 更新频率
- 每周迭代，结合新热度与口碑反馈

## 注意事项
- 高峰期排队较久，建议提前预约或错峰
- 部分项目有拍摄限制或最低消费，按现场规则执行

---
name: "Nearby Conference Centers"
description: "Find nearby conference centers. Invoke when user asks for conference venues near me."
---

# Nearby Conference Centers

用途
- 提供用户当前位置附近的 Conference Centers 列表
- 统一返回字段与查询行为，便于前端/接口复用
- 适用于会议场地、活动空间、会展中心等就近查询

触发条件
- 用户询问“Conference Centers 附近 / conference center near me / event venue near me”
- 用户提供定位/城市并希望“找/推荐/看看附近的 Conference Centers”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 5000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（min_rating、price_level、keywords 等）

响应字段
- 统一参见 STANDARD_RESPONSE.md
- 本技能 category 固定为 "conference-centers"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 5000, limit: 10 }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理
- 建议对同一 location+category+radius 做短时缓存以降低频率

---
name: "Nearby Clinics"
description: "Find nearby clinics. Invoke when user asks for a clinic near me."
---

# Nearby Clinics

用途
- 提供用户当前位置附近的 Clinics 列表
- 统一返回字段与查询行为，便于前端/接口复用
- 适用于“门诊/诊所/看病/体检”等就近查询场景

触发条件
- 用户询问“Clinics 附近 / clinic near me / nearby clinic”
- 用户提供定位/城市并希望“找/推荐/看看附近的 Clinics”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 5000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（open_now、min_rating、keywords 等）

响应字段
- 统一参见 STANDARD_RESPONSE.md
- 本技能 category 固定为 "clinics"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 5000, limit: 10, filters: { open_now: true } }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理
- 建议对同一 location+category+radius 做短时缓存以降低频率

---
name: "Nearby Camping Sites"
description: "Find nearby camping sites. Invoke when user asks for camping near me."
---

# Nearby Camping Sites

用途
- 提供用户当前位置附近的 Camping Sites 列表
- 统一返回字段与查询行为，便于前端/接口复用
- 适用于露营地/营地/房车营地等就近查询与出行规划

触发条件
- 用户询问“Camping Sites 附近 / camping near me / nearby campsite”
- 用户提供定位/城市并希望“找/推荐/看看附近的 Camping Sites”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 8000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（open_now、min_rating、keywords 等）

响应字段
- 统一参见 STANDARD_RESPONSE.md
- 本技能 category 固定为 "camping-sites"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 8000, limit: 10 }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理
- 建议对同一 location+category+radius 做短时缓存以降低频率

---
name: "附近共享办公"
description: "Find nearby coworking spaces. Invoke when user asks for shared offices near me."
---

# Nearby Coworking Spaces

用途
- 提供用户当前位置附近的 Coworking Spaces 共享办公列表
- 统一返回字段与查询行为，便于前端/接口复用

触发条件
- 用户询问“共享办公 附近 / coworking spaces near me / shared offices”

输入参数
- location: 经纬度 { lat, lng }，必填
- radius_meters: 查询半径，默认 3000
- limit: 返回数量上限，默认 20，最大 50
- filters: 可选筛选（是否按日租、会议室、咖啡、评分等）

响应字段
- 统一参见 [STANDARD_RESPONSE.md](file:///Users/mac_lkm/workspace/trae/100fj/.trae/skills/STANDARD_RESPONSE.md)
- 本技能 category 固定为 "coworking-spaces"

错误码
- INVALID_LOCATION: 经纬度不合法
- RADIUS_TOO_LARGE: 超过最大查询半径
- PROVIDER_UNAVAILABLE: 数据源不可用
- RATE_LIMITED: 触发速率限制

示例
- 输入: { location: { lat: 30.123, lng: 120.456 }, radius_meters: 2500, limit: 10 }
- 输出: 标准 POI 列表（见 STANDARD_RESPONSE.md）

隐私与速率限制
- 仅在用户授权定位后查询
- 避免保留精确坐标，必要时进行网格化模糊处理