capture-work-items

Skill: Capture Work Item

Purpose

Capture requirements, bugs, or issues from free-form input and convert them into structured, persistent artifacts. Provide fast structured recording without the deep validation performed by "Analyze Requirements". Keep output paths consistent with the project documentation structure (e.g., project documentation templates), and include governance status tracking.

Core Objective

Primary Objective: Convert the requirement, bug, or issue description provided by the user into a structured work item with all required fields, and persist it to the project-agreed path.

Success Criteria(all requirements must be met):

✅ Identified type: work item classified as requirement, bug, or issue
✅ Required fields complete: all required fields for that type are filled in (no inference; ask the user when missing)
✅ Status setting: the preceding initial状态：已捕获
✅ strategic_goal_id marked: required for each work item strategic_goal_id, mapped to one goal in the project strategic-goals (per ADR 20260417-unified-value-driven-prioritization-model decision 3.4)
✅ priority marked as unset: newly created work item frontmatter must include priority: unset, awaiting prioritize-backlog batch scoring
✅ Detected path: output path selected according to the project documentation structure (see Path Detection)
✅ Artifact persistence: work item written to the selected path
✅ User confirmation: the user explicitly confirms or delegates the write
✅ Suggest priority scoring after batch capture: at the end of batch capture, count the total number of unscored backlog items and suggest (not automatically executed) running prioritize-backlog

Acceptance Test: Can a person or downstream system read the artifact and understand the complete work item and act on it without asking clarifying questions?

Scope Boundaries

This skill is responsible for：

Free-form input → structured work item
Single or batch capture (batch: confirm by project or batch)
Output to local Markdown under the project-agreed path
Status lifecycle: only the initial "Captured" (downstream updates "Triaged", "In Progress", "Done", "Blocked", "Cancelled")

This skill is not responsible for：

In-depth requirement clarification or validation → use "Analyze Requirements"
Design or architecture → use "Design Solution"
Direct API calls to Zentao/GitHub to create issues (extension point; not required for v1)

Handoff point: after the artifact is persisted and the user confirms, if the project requires deeper validation, hand off to "Analyze Requirements", or hand off to process management/milestones for planning.

Use Cases

Quick backlog entry: the user says "record this bug" or "add this requirement" - structure and persist without full analysis.
Meeting/email capture: extract work items from meeting notes or emails and save them as structured artifacts.
Triaged input: Capture items for later classification and prioritization in milestones or task breakdowns.
Backlog evidence: Fill backlog gaps identified in the assessment document (e.g., "Backlog: Weak - no clear to-do document").

Behavior (behavior)

Interaction (interaction) policy

Default: Path to the project specification or spec/product contract; typed from input
Select option: One missing field question at a time; provide options when applicable
Confirm: Target path when different from the default path; user confirms before writing

Resolve the project specification in the discovery order of §8.2 → determine the backlog-item of path_pattern(default:docs/process-management/project-board/backlog/YYYY-MM-DD-{slug}.md or fallback docs/backlog/YYYY-MM-DD-{slug}.md; projects may override to aggregate style)
Replace using the placeholder syntax of §8.3; for unresolved placeholders, ask the user per §8.6
If the caller frontmatter input contains upstream_ref(should point to an upstream roadmap entry or requirement): in the frontmatter of the produced artifact emit parent: <upstream_ref>
Record resolved_path + frontmatter delta for use in subsequent writes

Note: By default, retain the §3 path detection logic (docs/process-management/ presence determines canonical vs fallback), but if the project declares an explicit ARTIFACT_NORMS.md in path_pattern, the project declaration takes precedence.

Path detection

Use the resolved specification (or contract default) to select the output path:

Condition	Output path
`docs/process-management/` exists	`docs/process-management/project-board/待办/YYYY-MM-DD-<slug>.md`
Otherwise	`docs/待办/YYYY-MM-DD-<slug>.md`

If the subdirectories do not exist, create them. Use "YYYY-MM-DD" for today; <slug> is kebab-case in the title.

Phase 0: Classification — Identify the type

Announce at the start:"I am using the capture work item skill to record this work item."

Classify the input as:

Requirement: New requirement, feature request, or enhancement
bug: Defect, incorrect behavior, failure to meet specification
Issue: Task, improvement, or issue (generic work item)

Phase 1: Extraction — Identify fields

Extract available fields from the input. Required fields by type:

Type	Required fields
Requirement	Title, problem/requirement, acceptance criteria,strategic_goal_id
Bug	Title, description, reproduction steps, expected vs actual, severity,strategic_goal_id
Issue	Title, description, type (task\|improvement\|issue),strategic_goal_id

strategic_goal_id description：

Read docs/project-overview/strategic-goals.md, present the list of optional goals to the user
The user selects which strategic goal this work item primarily serves
If strategic-goals.md does not exist → halt, suggest running design-strategic-goals
Bug / technical debt work items usually map to the "Engineering / Governance Health" goal (per ADR 1 Decision 3.5)

Phase 2: Prompt — Fill in missing required fields

For any missing required fields, ask the userone question at a time. Do not infer or guess.

Phase 3: Persist — Write the artifact

Run "Resolve project conventions", then run "Path detection" (see above)
If the target path differs from the default path, confirm with the user
Write Markdown with YAML front-matter using the appropriate template (see Output templates)
Set in front-matter status: capture

Phase 4: Confirm

Confirm with the user that the artifact has been written and is complete. Do not commit to version control unless the user explicitly requests it.

Phase 5: Suggest batch scoring (do not execute automatically)

At the end of capture (single item or batch), perform the following suggest action：

Scan the backlog directory and count priority: unset the total number of entries
If ≥ threshold (default ≥ 3) or this batch capture ≥ 2 items, output a suggestion:

"The backlog currently has N entries with undetermined priority. It is recommended to run prioritize-backlog batch scoring before the next planning. This skill will not call it automatically — the user decides the timing (batch scoring is higher quality when there is a control group)."
Do not execute automatically prioritize-backlog(for the rationale, see ADR 2 Decision 3.7.1: the two skills have different rhythms, and forcing chaining damages scoring quality)

Input & Output (Input & Output)

Input (Input)

The user's raw description of the requirement, bug, or issue
Optional: project context (existing "docs/" structure used for path detection)

Output (Output)

A structured work item Markdown file with YAML front-matter. The template is as follows.

Requirement template

---
artifact_type: backlog-item
created_by: capture-work-items
lifecycle: living
type: requirement
date: YYYY-MM-DD
status: captured
priority: unset
strategic_goal_id: [goal-N]
source: [user|meeting|email]
trace_id: optional
---

# [Title]

## Problem / Need
[Who has what problem; no solution language]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Notes
[Optional]

Bug template

---
artifact_type: backlog-item
created_by: capture-work-items
lifecycle: living
type: bug
date: YYYY-MM-DD
status: captured
priority: unset
strategic_goal_id: [goal-N]
severity: [critical|major|minor]
---

# [Title]

## Description
[What goes wrong]

## Steps to Reproduce
1. ...
2. ...

## Expected vs Actual
- **Expected**: ...
- **Actual**: ...

## Environment
[Optional]

Issue template

---
artifact_type: backlog-item
created_by: capture-work-items
lifecycle: living
type: issue
subtype: [task|improvement|question]
date: YYYY-MM-DD
status: captured
priority: unset
strategic_goal_id: [goal-N]
---

# [Title]

## Description
[Content]

Status lifecycle

This skill only sets "status: captured". Downstream processes (milestones, escalation iteration tasks, run checkpoints) may update it to: "triaged", "in progress", "done", "blocked", "cancelled".

Constraints (Constraints)

Hard Boundaries (Hard Boundaries)

Do not skip required fields: If required fields cannot be inferred, ask the user. Do not leave them blank.
Do not skip strategic_goal_id：strategic-goals.md when it does not exist, halt and suggest running design-strategic-goalsfirst; do not leave it blank or infer it.
Do not automatically call prioritize-backlog: At the end of capture, only suggest it; the user decides when to batch score (different rhythms, single-item scoring is distorted).
No diagnostic flow: Do not run diagnostic states (RA0–RA5). If the input content is very vague, suggest capturing first, confirming intent, and then clarifying in depth.
Confirm the path before writing: Avoid overwriting existing files; confirm when the target path is unclear.
Paths follow the project structure: Use path detection rules; do not hard-code a single path.

Skill Boundaries (Skill Boundaries) (avoid overlap)

Do not do these(other skills can handle them):

In-depth requirement validation: diagnostic states, issue clarification, scope boundaries → use "Analyze requirements"
Design and architecture: solutions, alternatives, trade-offs → use "Design solution"
Task decomposition: Epic/task breakdown, acceptance criteria refinement → use process management or implementation plan

When to stop and hand off：

User says "this needs more analysis" → hand off to "analyze requirements"
User says "design this" → hand off to "design solution"
Artifact retained and confirmed → handoff complete

Self-Check

Core success criteria (all criteria must be met)

Identified type: the work item is a requirement, bug, or issue
Required fields completed: all required fields are completed (no inference)
strategic_goal_id marked: mapped to a specific goal in strategic-goals
priority is unset: frontmatter contains priority: unset
Status set: "Status: Captured" in the preceding content
Path detected: output path follows path detection rules
Artifact retained: file written to the selected path
User confirmation: user confirms or delegates writing
Suggest batch scoring: in batch scenarios, suggest the user run prioritize-backlog(but do not execute automatically)

Process quality check

One question at a time: did not overwhelm the user with questions about multiple missing fields
No solution language in the requirement: the issue/requirement describes the problem, not the implementation
Path creation: create if needed待办/subdirectory
Filename convention: use YYYY-MM-DD-{slug}.md

Acceptance test

Can a person or downstream system read the artifact and understand the complete work item and act on it without asking clarifying questions?

If no: required fields are incomplete. Return to the prompt phase.

If yes: capture complete. Hand off as needed.

Examples

Example 1: Bug capture

User: "When I use special characters in the password field, the login page shows 500."

Agent announces: "I am using the capture work item skill to record this work item."

Classification: classified as a bug.

Excerpt: title and description exist; reproduction steps, expected vs. actual, and severity are missing.

Prompt(one at a time):

Agent: "What are the specific steps to reproduce this?"

User: "1. Go to /login 2. Enter any username 3. Enter a password with @ or # 4. Click "Login""

Agent: "How does what you expected differ from what actually happened?"

User: "Expected: normal login or validation error. Actual: 500 Internal Server Error."

Agent: "What severity would you assign: critical, major, or minor?"

User: "Major."

Persist: path detected - docs/process-management/ Exists. Write to "docs/process-management/project-board/待办/2026-03-06-login-500-special-chars.md".

Confirm: "Written. Would you like to adjust anything or hand off for triage?"

Example 2: Requirements capture — vague input

User: "We need better error messages."

Agent announces: "I am using the capture work item skill to record this work item."

Classification: Classified as requirement (possibly a problem; the agent chooses requirement as the default "need").

Excerpt: Title can be derived ("better error messages"); missing problem/requirement and acceptance criteria.

Prompt：

Agent: "Who is encountering this problem? What exactly is wrong with the current error messages?"

User: "Our API users get a generic 'something went wrong' but no actionable information."

Agent: "What would 'done' look like—at least one concrete acceptance criterion?"

User: "The error response should include a code (e.g., ERR_001) and a short human-readable message explaining what went wrong."

Continue: Path detected - docs/process-management/ does not exist. Write to "docs/待办/2026-03-06-better-error-messages.md".

Handoff suggestion: "This may benefit from deeper validation of the analysis requirements. Continue with capture only, or hand off for full analysis?"

User: "Capture only for now."

Confirm: "Written. Hand off for triage when ready."

Example 3: Problem capture — edge case (multiple items in one message)

User: "Two things: 1) Update the README installation section. 2) Add CONTRIBUTING.md."

Agent announces: "I am using the capture work item skill. I see two separate work items. I will capture them one at a time."

Item 1 — Type: problem (task). Title: "Update README installation section". Description: from context. Save as "2026-03-06-update-readme-install.md".

Item 2 — Type: problem (task). Title: "Add CONTRIBUTING.md". Description: from context. Save as "2026-03-06-add-contributing.md".

Confirm: "Both items have been captured. Review and adjust if needed."