菜单
Write OpenSpec proposal.md artifacts (why + what). TRIGGER when: capturing requirements, scope, and impact for a spec-driven feature. SKIP: technical design (use spec-design); external documentation research (use research-methodology).
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | spec-research |
| description | Write OpenSpec proposal.md artifacts (why + what). TRIGGER when: capturing requirements, scope, and impact for a spec-driven feature. SKIP: technical design (use spec-design); external documentation research (use research-methodology). |
Guide for creating proposal.md -- the WHY document that anchors the entire workflow.
Write to: {specs_path}/proposal.md
Path Enforcement: The specs_path MUST be .scaffolding/conversations/{UUID}/specs/ where {UUID} is a valid UUID (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). NEVER use descriptive folder names.
| Section | Purpose | Content |
|---|---|---|
| Why | Motivation | 1-2 sentences. What problem? Why now? |
| What Changes | Scope | Bullet list. New capabilities, modifications, removals. Mark BREAKING |
| Capabilities | Contract | New + modified capabilities (kebab-case names) |
| Impact | Blast radius | Affected code, APIs, dependencies, systems |
| Agent Assignment | Routing | Table of agents, roles, artifacts |
| Rollback Plan | Safety | Revert points, manual steps, affected systems |
This section creates the contract between proposal and design phases.
user-auth, data-export, api-rate-limiting.scaffolding/openspec/specs/ for existing names## Why
[1-2 sentences: problem + urgency]
## What Changes
- [Specific change 1]
- [Specific change 2]
- **BREAKING**: [Breaking change, if any]
## Capabilities
### New Capabilities
- `capability-name`: Brief description
### Modified Capabilities
- `existing-name`: What requirement is changing
## Impact
[Affected code, APIs, dependencies, systems]
## Agent Assignment
| Agent | Role | Artifacts |
|-------|------|-----------|
| architect | Analyst + Coordinator | proposal.md, design.md, tasks.md |
| researcher | External Research (if needed) | ResearchPack |
| developer | Developer | Source code |
| reviewer | Reviewer | Review report |
## Rollback Plan
- [ ] Identify revert points
- [ ] Document manual rollback steps
- [ ] List affected systems
| Avoid | Instead |
|---|---|
| Vague goals ("improve performance") | Measurable goals ("reduce p95 latency below 200ms") |
| Implementation details | Save for design.md |
| Missing rollback plan | Always include revert strategy |
| Skipping capabilities section | This is the design contract |
SendMessage recipient validation and worktreePath safety (CWE-59). TRIGGER when: validating a SendMessage `to:` recipient against the agent whitelist, or a worktreePath from another agent before acting on it. SKIP: routing topology (agent Comms Protocol); git ops (use git-operations); worktree recovery (use worktree-management).
Python backend patterns: layered architecture, async I/O, dependency injection, repository/service separation. TRIGGER when: creating routes, models, schemas, or services in a Python backend. SKIP: REST contract design (use api-design); schema/index tuning (use database-optimization). (Examples: FastAPI + SQLAlchemy + Pydantic.)
Knowledge distillation methodology: candidate extraction, confidence scoring, tier routing, conversation-scoped mode. TRIGGER when: running /learn or /distill, deciding if an insight is memory-worthy, or scoring a knowledge candidate. SKIP: ad-hoc memory reads/writes (use agent-memory); vector storage (use semantic-memory-store).
Build minimal, reversible implementation plans. TRIGGER when: turning research into a plan, or sequencing work before writing code. SKIP: gathering documentation (use research-methodology); writing OpenSpec design.md/tasks.md (use spec-design).
Score ResearchPacks (>=80) and Implementation Plans (>=85) against quality gates. TRIGGER when: gating research or a plan before implementation. SKIP: writing or running tests (use testing-strategy); security threat review (use security-review-checklists).
Optimize Claude Code context-window usage for accuracy and cost. TRIGGER when: hitting context limits, structuring prompts for an agent, or trimming what gets injected into a task. SKIP: persisting knowledge across sessions (use agent-memory); semantic recall tuning (use semantic-memory-mcp).