/pair-capability-write-issue — PM Tool Issue Writer

Create or update issues in the adopted PM tool. Template-driven: reads the type-specific template, formats the issue body accordingly, and creates or updates via the PM tool API.

Arguments

Argument	Required	Description
`$type`	Yes	Issue type: `story`, `task`, `epic`, or `initiative`. Determines which template is used.
`$content`	Yes	Structured content to fill the template — fields map to template sections.
`$id`	No	Existing issue identifier. If provided → update; if absent → create.
`$parent`	No	Parent issue identifier for hierarchy linking (e.g., epic → story, story → task).
`$status`	No	Target status for the project board field (e.g., `Refined`, `In Progress`, `Done`). If provided, updates the project board status field per the implementation guide.

Algorithm

Step 1: Validate Arguments

Check: Is $type one of the supported types (story, task, epic, initiative)?
Skip: If valid, proceed to Step 2.
Act: If unsupported type → HALT:

Unsupported issue type: $type. Supported: story, task, epic, initiative.
Verify: $type is valid.

Step 2: Detect PM Tool

Check: Read way-of-working.md and identify the adopted PM tool.
Skip: If PM tool is identified, proceed to Step 3.
Act: If no PM tool configured → HALT:

No PM tool configured in way-of-working.md. Configure via /pair-capability-setup-pm or manually set the PM tool in way-of-working.md.
Verify: PM tool identified (e.g., github-projects, jira, linear, filesystem).

Step 3: Load Template

Check: Resolve template path based on $type:
- story → user-story-template.md
- task → task-template.md
- epic → epic-template.md
- initiative → initiative-template.md
Skip: If template file found, proceed to Step 4.
Act: If template not found → HALT:

Template not found: [template path]. Ensure the knowledge base is installed.
Verify: Template loaded and parsed.

Step 4: Format Issue Body

Check: Does $content contain all required fields for the template?
Act: Fill the template sections with $content data:
- Match $content fields to template sections.
- Preserve template structure and section ordering.
- Omit optional sections that have no content (do not leave empty placeholders).
Verify: Issue body is formatted following the template structure.

Step 5: Load PM Tool Implementation Guide

Check: Resolve the PM tool implementation guide based on the adopted tool:
- github-projects → github-implementation.md
- filesystem → filesystem-implementation.md
- Other tools → use the tool-specific guide if available.
Skip: If guide found, proceed to Step 6.
Act: If guide not found, warn and proceed with best-effort PM tool interaction:

PM tool implementation guide not found for [tool]. Proceeding with default behavior.
Verify: Implementation guide loaded (or warning issued).

Step 6: Create or Update Issue

Check: Is $id provided?
- $id absent → Create mode: Create a new issue in the PM tool.
- $id present → Update mode: Verify the issue exists, then update it.
Act (Create):
- Create issue with the formatted body.
- Apply labels based on $type (e.g., user story, task, epic, initiative).
- If $parent is provided, link to parent issue (hierarchy: epic → story → task).
- Configure project field settings (priority, type, status) per the implementation guide.
- Record the new issue identifier for return.
Act (Update):
- Read the existing issue to confirm it exists.
- If not found → HALT: Issue #$id not found.
- Update the issue body with the formatted content.
- Preserve existing labels and hierarchy links unless explicitly changed.
- If $status is provided, update the project board status field per the implementation guide (e.g., GraphQL mutation for GitHub Projects). This is the board field, not the body text.
Verify: Issue created or updated successfully. If $status was provided, confirm the board field reflects the new status.

Step 7: Handle Errors

Check: Did the PM tool return an error during Step 6?
Skip: If no error, proceed to output.
Act: HALT with descriptive error:

PM tool error: [error description]. No fallback to alternative tools — resolve the issue with the adopted PM tool and re-invoke.
Verify: Error reported to developer.

Output Format

ISSUE WRITTEN:
├── Mode:     [Created | Updated]
├── Type:     [story | task | epic | initiative]
├── ID:       [issue identifier — e.g., #42]
├── PM Tool:  [adopted tool name]
├── Template: [template file used]
├── Parent:   [parent issue ID or "none"]
└── Status:   [Success | HALT — reason]

Return value: The issue identifier (e.g., #42) — used by composing skills in chain operations.

Composition Interface

When composed by /pair-process-refine-story:

Input: /pair-process-refine-story invokes /pair-capability-write-issue with $type: story, $content containing the refined story data, $id when updating an existing story, and $status: Refined to transition the board field.
Output: Returns the issue identifier. /pair-process-refine-story uses it for linking.

When composed by /pair-process-plan-tasks:

Input: /pair-process-plan-tasks invokes /pair-capability-write-issue with $type: story, $id: [story-id], and $content containing the Task Breakdown section to append. Tasks are documented inline in the story body — no separate task issues are created.
Output: Returns the story issue identifier. /pair-process-plan-tasks confirms the update.

When composed by /pair-process-plan-initiatives:

Input: /pair-process-plan-initiatives invokes /pair-capability-write-issue with $type: initiative and $content containing the initiative data. Passes $id when updating an existing initiative.
Output: Returns the issue identifier. /pair-process-plan-initiatives uses it for linking and status tracking.

When composed by /pair-process-plan-epics:

Input: /pair-process-plan-epics invokes /pair-capability-write-issue with $type: epic, $content containing the epic data, and $parent linking to the parent initiative.
Output: Returns the issue identifier. /pair-process-plan-epics uses it for linking stories.

When composed by /pair-process-plan-stories:

Input: /pair-process-plan-stories invokes /pair-capability-write-issue with $type: story, $content containing the story data, and $parent linking to the parent epic.
Output: Returns the issue identifier. /pair-process-plan-stories uses it for status tracking.

When invoked independently:

Interactive: create or update an issue directly in the adopted PM tool.
All arguments must be provided (or prompted interactively).
Returns the issue identifier.

HALT Conditions

Unsupported $type (Step 1) — lists currently supported types.
No PM tool configured (Step 2) — directs to configuration.
Template not found (Step 3) — missing knowledge base file.
$id provided but issue not found (Step 6) — issue does not exist.
PM tool error (Step 7) — no fallback, descriptive error reported.

Extensibility

This skill supports story, task, epic, and initiative types. Adding a new type requires: (1) a new template file in collaboration/templates/, (2) a new entry in Step 1 validation, (3) a new entry in Step 3 template resolution, (4) a new entry in the Composition Interface section.

Graceful Degradation

If way-of-working.md is not found, HALT — PM tool is required.
If the template file is not found, HALT — template-driven formatting is mandatory.
If the PM tool implementation guide is not found, warn and proceed with default behavior.
If the PM tool is not accessible (auth failure, rate limit, network), HALT with descriptive error — no fallback.

Notes

This skill modifies PM tool state — it creates and updates issues.
No PM tool fallback: if the adopted tool fails, the skill HALTs. The developer resolves the issue, then re-invokes (idempotent by design — $id prevents duplicate creation).
Template = source of truth for issue body format. Changes to template structure automatically affect all future issue creation.
Labels and hierarchy linking follow the PM tool implementation guide conventions.

pair-capability-write-issue

SKILL.md.claude/skills/pair-capability-write-issue/SKILL.md