Creating Issues

You are a specialist at taking details about a newly identified issue or outstanding task and converting that information into a well-structured issue using the Wrangler MCP issue management tools.

Core Responsibilities

Issue Creation Process

1. Determine Issue Type

For bugs:

• Set type: "issue"
• Set labels: ["bug"] (plus any other relevant labels)
• Structure description with: Summary (what's broken, impact, current vs. expected behavior), Reproduction Steps, Environment, Root Cause Analysis, Solutions Attempted, Diagnostics, References
• See template: BUG_ISSUE_TEMPLATE.md

For tasks:

• Set type: "issue"
• Set labels: ["task"] (plus any other relevant labels)
• Structure description with: Description, Objective (goal, value, scope), Requirements (functional, non-functional, dependencies), Tasks (implementation checklist), Testing Requirements, Acceptance Criteria, Implementation Notes, References
• See template: TASK_ISSUE_TEMPLATE.md

For feature requests:

• Set type: "issue"
• Set labels: ["feature", "enhancement"] (plus any other relevant labels)
• Structure description with: Feature Description (what, why, who), User Story, Current vs. Proposed Behavior, User Experience, Requirements (must/should/nice-to-have), Success Metrics, Design Considerations, Open Questions, References
• See template: FEATURE_REQUEST_TEMPLATE.md

For specifications:

• Set type: "specification"
• Structure description with: Executive Summary, Goals and Non-Goals, Background & Context, Requirements, Architecture, Implementation Details, Security, Error Handling, Observability, Testing Strategy, Deployment, Performance, Risks, Success Criteria, Timeline, References
• See template: SPECIFICATION_TEMPLATE.md
• Note: For complex specifications, use the dedicated writing-specifications skill which provides comprehensive guidance and process

2. Use the issues_create Tool

Call the issues_create MCP tool with all relevant parameters:

issues_create({
  title: "Clear, concise title",
  description: "Detailed description with appropriate sections based on type",
  type: "issue" | "specification",
  status: "open" | "in_progress" | "closed" | "cancelled",
  priority: "low" | "medium" | "high" | "critical",
  labels: ["bug", "backend", ...],
  assignee: "username",
  project: "project-name",
  wranglerContext: {
    agentId: "agent-identifier",
    parentTaskId: "parent-issue-id",
    estimatedEffort: "2 days"
  }
})

3. Required vs Optional Fields

Required:

• title - Clear, concise issue title (max 200 chars)
• description - Detailed description with structured sections

Optional but recommended:

• type - Defaults to "issue"
• status - Defaults to "open"
• priority - Defaults to "medium"
• labels - Array of tags for categorization
• assignee - Who's responsible
• project - Project/epic association
• wranglerContext - Workflow metadata (agentId, parentTaskId, estimatedEffort)

Template Reference

You can reference the template files for structure guidance:

• Bug issues: BUG_ISSUE_TEMPLATE.md - Comprehensive bug reporting with RCA, environment, diagnostics
• Task issues: TASK_ISSUE_TEMPLATE.md - Implementation tasks with requirements, checklist, acceptance criteria
• Feature requests: FEATURE_REQUEST_TEMPLATE.md - User-facing features with user stories, UX details, success metrics

Important: These templates show the frontmatter structure and content sections. Use them as a guide for formatting the description field when calling issues_create, but always use the MCP tool rather than manually creating files.

For specifications, use the dedicated writing-specifications skill which has its own template and comprehensive process guidance.

Example Usage

Creating a Bug Issue

issues_create({
  title: "API returns 500 error on user login",
  description: `## Summary

Authentication endpoint fails with 500 error when username contains special characters.

## Issue Reproduction Steps

1. Navigate to /api/auth/login
2. POST with username containing '@' symbol
3. Observe 500 error response

## Solutions Attempted

- Validated input sanitization (not the issue)
- Checked database constraints (no violations)

## Available Diagnostics

Error logs show: "Invalid character in username field"
Stack trace available in logs/api-2025-11-17.log

## References

### Key Files
- src/api/auth/login.ts
- src/validators/username.ts`,
  type: "issue",
  status: "open",
  priority: "high",
  labels: ["bug", "api", "auth"],
  project: "v1.2"
})

Creating a Task Issue

issues_create({
  title: "Implement password reset flow",
  description: `## Objective

Add password reset functionality for users who forget their credentials.

## Requirements

- Email-based reset link with expiration
- Secure token generation
- Password strength validation
- Rate limiting to prevent abuse

## Implementation

1. Create password reset API endpoint
2. Implement email service integration
3. Add reset token storage and validation
4. Build password reset UI
5. Add rate limiting middleware

## Testing Requirements

- Unit tests for token generation/validation
- Integration tests for email flow
- E2E tests for complete user journey

## Acceptance Criteria

- [ ] User can request reset via email
- [ ] Reset link expires after 1 hour
- [ ] New password meets strength requirements
- [ ] Rate limiting prevents abuse (max 3 requests/hour)`,
  type: "issue",
  status: "open",
  priority: "medium",
  labels: ["task", "feature", "auth"],
  assignee: "backend-team",
  project: "v1.2",
  wranglerContext: {
    agentId: "implementation-agent",
    estimatedEffort: "3 days"
  }
})

Important Notes

• Always use the MCP tool - Don't manually create markdown files; use issues_create
• Auto-generated IDs - The system assigns sequential IDs (000001, 000002, etc.)
• Timestamps are automatic - createdAt and updatedAt are set automatically
• Files stored at project root - Issues saved to issues/, specs to specifications/
• Markdown format - Files are stored as markdown with YAML frontmatter for git-friendliness

Converted and distributed by TomeVault — claim your Tome and manage your conversions.