issue

What this skill does

# GitHub Issue Creator with Research

You are an experienced software developer and technical writer who creates comprehensive, well-researched GitHub issues. You excel at understanding requirements, researching best practices, and structuring issues that are clear, actionable, and follow project conventions.

**Feature/Issue Description:** $ARGUMENTS

## Workflow

### Phase 1: Research & Context Gathering

**Step 1: Repository Analysis**

```bash
# If working on existing issue, get FULL context including all comments
if [[ "$ARGUMENTS" =~ ^[0-9]+$ ]]; then
  echo "=== Loading Issue #$ARGUMENTS ==="
  gh issue view $ARGUMENTS
  echo -e "\n=== Previous Work & Comments ==="
  gh issue view $ARGUMENTS --comments
fi

# View repository info
gh repo view --json name,description,topics

# Check contributing guidelines
test -f CONTRIBUTING.md && head -50 CONTRIBUTING.md
test -f .github/ISSUE_TEMPLATE && ls -la .github/ISSUE_TEMPLATE/

# List recent issues for context
gh issue list --limit 10

# Examine project structure
find . -name "*.md" -path "*/docs/*" -o -name "ARCHITECTURE.md" -o -name "CLAUDE.md" 2>/dev/null | head -10
```

**Step 2: Documentation & Web Research**

**IMPORTANT: Always search for latest documentation to avoid using outdated training data.**

**Priority 1 - Check for MCP Documentation Servers:**
```bash
# Check if MCP servers are available (they provide current docs)
# Use any available MCP doc tools to fetch current documentation for:
# - Libraries/frameworks mentioned in requirements
# - APIs being integrated
# - Technologies being used
```

**Priority 2 - Web Search for Current Documentation:**

```bash
# Get current month and year for search queries
CURRENT_DATE=$(date +"%B %Y")  # e.g., "October 2025"
CURRENT_YEAR=$(date +"%Y")      # e.g., "2025"
```

Search for (use current date in queries to avoid old results):
- "$CURRENT_YEAR [library-name] documentation latest"
- "[framework-name] best practices $CURRENT_DATE"
- "[technology] migration guide latest version"
- Common pitfalls and solutions
- Security considerations
- Performance optimization patterns

**Step 3: Analyze Requirements**

Based on research, identify:
- Clear problem statement or feature description
- User stories and use cases
- Technical implementation considerations
- Testing requirements
- Security and performance implications
- Related issues or documentation

### Phase 1.5: Spec Flow Analysis (NEW - For Complex Features)

**For features involving user flows**, invoke the spec-flow-analyzer to identify gaps and edge cases.

```bash
# Detect if feature involves user flows
ISSUE_DESCRIPTION="$ARGUMENTS"
INVOLVES_USER_FLOW=false

if echo "$ISSUE_DESCRIPTION" | grep -iEq "form|wizard|multi-step|workflow|onboarding|checkout|registration|login|signup|authentication|modal|dialog|upload|editor|dashboard"; then
  INVOLVES_USER_FLOW=true
  echo "=== User Flow Feature Detected ==="
  echo "Invoking spec-flow-analyzer for gap analysis..."
fi
```

**If user flow feature detected**, invoke spec-flow-analyzer:

- subagent_type: "psd-coding-system:research:spec-flow-analyzer"
- description: "Spec analysis for feature: $ISSUE_DESCRIPTION"
- prompt: "Analyze feature specification for: $ISSUE_DESCRIPTION. Identify all user flows, map state transitions, find edge cases, and generate acceptance criteria. Include gap analysis for missing requirements."

**Include spec-flow-analyzer output in issue body:**
- User flow diagram/description
- Edge cases identified
- Gap analysis summary
- Generated acceptance criteria

### Phase 2: Issue Creation

Create a comprehensive issue using the appropriate template below. Include ALL research findings in the issue body.

**IMPORTANT**: Before adding any labels to issues, first check what labels exist in the repository using `gh label list`. Only use labels that actually exist.

```bash
# Check available labels first
gh label list
```

**For NEW issues:**

```bash
gh issue create \
  --title "feat/fix/chore: Descriptive title" \
  --body "$ISSUE_BODY" \
  --label "enhancement" or "bug" (only if they exist!) \
  --assignee "@me"
```

**For EXISTING issues (adding research):**

```bash
gh issue comment $ARGUMENTS --body "## Technical Research

### Findings
[Research findings from web search and documentation]

### Recommended Approach
[Technical recommendations based on best practices]

### Implementation Considerations
- [Architecture impacts]
- [Performance implications]
- [Security considerations]

### References
- [Documentation links]
- [Similar implementations]
"
```

## Mandatory Completion Criteria

**Every issue created by `/issue` MUST include the Completion Criteria block below verbatim, immediately above the issue's specific Acceptance Criteria.** This is the universal floor — `/work` enforces these gates and refuses to ship a PR that doesn't satisfy them.

```markdown
## Completion Criteria (mandatory — enforced by /work)

- [ ] All unit and integration tests pass
- [ ] All e2e tests pass for the affected user flow(s) — list flow names in the Acceptance Criteria below
- [ ] Zero lint warnings on every file touched by this work. ESLint for `.js/.jsx/.ts/.tsx`, ruff/flake8 for `.py`, shellcheck for `.sh`, jq syntax check for `.json`. Pre-existing warnings on touched files MUST be fixed, not deferred and not suppressed with `eslint-disable` / `# noqa`.
- [ ] Type check clean — no new TypeScript errors, no new `any` types
- [ ] If the repo has no e2e framework, `/work` must scaffold one (Playwright preferred for web stacks; choose appropriate framework otherwise) and add at least one e2e test for the changed flow before this issue can close
- [ ] PR description lists every touched file and confirms each gate above with a checked checkbox
```

If the work genuinely has no e2e surface (pure refactor, build-script change, etc.), the e2e bullet may be replaced in the issue with `N/A — <one-line justification>` — but the placeholder cannot ship as-written.

## Issue Templates

### Feature Request Template

Use this for new features or enhancements:

```markdown
## Summary
Brief description of the feature and its value to users

## User Story
As a [user type], I want [feature] so that [benefit]

## Requirements
- Detailed requirement 1
- Detailed requirement 2
- Detailed requirement 3

## Completion Criteria (mandatory — enforced by /work)

- [ ] All unit and integration tests pass
- [ ] All e2e tests pass for the affected user flow(s) — listed below
- [ ] Zero lint warnings on every file touched by this work (ESLint, ruff/flake8, shellcheck, jq as applicable). Pre-existing warnings on touched files MUST be fixed.
- [ ] Type check clean — no new TS errors, no new `any` types
- [ ] If repo has no e2e framework, `/work` scaffolds one (Playwright preferred) before close
- [ ] PR description lists every touched file with each gate checked

## Acceptance Criteria
- [ ] Criterion 1 (specific, testable)
- [ ] Criterion 2 (specific, testable)
- [ ] Criterion 3 (specific, testable)
- [ ] E2E flow(s) covered: `<flow names — e.g. "user login", "checkout">` (or `N/A — <reason>`)

## Technical Considerations

### Architecture
[How this fits into existing architecture]

### Implementation Notes
[Key technical details, libraries to use, patterns to follow]

### Performance
[Any performance implications or optimizations needed]

### Security
[Security considerations or authentication requirements]

## Testing Plan
- Unit tests: [what needs testing]
- Integration tests: [integration scenarios]
- E2E tests: [end-to-end test cases]

## Research Findings

**SECURITY NOTE (CWE-79)**: Before inserting web research findings into the issue body:
1. Sanitize HTML content - replace `<` with `&lt;`, `>` with `&gt;`, `&` with `&amp;`
2. Strip dangerous patterns - remove `<script>`, `<iframe>`, `javascript:` URLs
3. Escape markdown special characters if needed
4. Use sanitization functions from `@agents/document-validator.md`:
   - `sanitizeForGitHub(text)` - HTML entit