gh-l-sypniewski-claude-code-toolkit-plugins-context-engineering/commands/initial-github-issue.md

# Format GitHub Issue for Context Engineering

## GitHub Issue URL: $ARGUMENTS

Transform a GitHub issue to follow the INITIAL.md format for context engineering workflow.

```initial.md
## FEATURE:

[Insert your feature here]

## EXAMPLES:

[Provide and explain examples that you have in the `examples/` folder]

## DOCUMENTATION:

[List out any documentation (web pages, sources for an MCP server like Crawl4AI RAG, etc.) that will need to be referenced during development]

## OTHER CONSIDERATIONS:

[Any other considerations or specific requirements - great place to include gotchas that you see AI coding assistants miss with your projects a lot]
```

## CRITICAL: Follow INITIAL.md Best Practices

When executing this command, you MUST follow these specific rules:

### FEATURE Section Rules

- ❌ **NEVER write vague descriptions** like "Build a web scraper" or "Create a contact form"
- ✅ **ALWAYS be specific and comprehensive** like "Build an async web scraper using BeautifulSoup that extracts product data from e-commerce sites, handles rate limiting, and stores results in PostgreSQL"
- Include specific technologies, libraries, and integration points
- Define exact functionality, validation, error handling, and UX requirements

### EXAMPLES Section Rules

- **Leverage the examples/ folder** - always check for relevant patterns
- **Provide specific file references** - not generic descriptions
- **Explain what aspects to mimic** - styling, validation, state management, etc.
- Reference existing components in the REWOS codebase that follow similar patterns

### DOCUMENTATION Section Rules

- **Include ALL relevant resources** with direct URLs
- API documentation with specific section links
- Library guides (Astro.js, React, Zod, Cloudflare Workers, etc.)
- MCP server documentation when applicable
- Database schemas (Strapi content types)

### OTHER CONSIDERATIONS Rules

- **Capture project-specific details** that AI agents commonly miss
- Authentication requirements, API keys, permissions
- Rate limits and quotas (especially Cloudflare Workers constraints)
- Performance requirements (Lighthouse scores, Core Web Vitals)
- Common pitfalls specific to REWOS architecture
- Browser compatibility and accessibility requirements

### CRITICAL: Ask for Missing Information - Never Assume

**When information is missing or unclear, STOP and ask for clarification:**

- ❌ **NEVER make assumptions** about missing requirements
- ❌ **NEVER fill in blanks** with generic or guessed information
- ✅ **ALWAYS ask specific questions** to get missing details
- ✅ **IDENTIFY gaps** and request clarification before proceeding

**Common areas that need clarification:**

- **User interactions**: What exactly should happen when user does X?
- **Data sources**: Where does the data come from? What's the schema?
- **Integration requirements**: How should this connect to existing systems?
- **Performance constraints**: Are there specific speed/size requirements?
- **Validation rules**: What are the exact validation requirements?
- **Error scenarios**: How should errors be handled and displayed?
- **Responsive behavior**: How should this work across different screen sizes?
- **Authentication/permissions**: Who can access this feature and how?

**Ask questions like:**

- "The issue mentions 'form validation' - what specific validation rules are needed?"
- "You mentioned 'data processing' - what's the expected data format and source?"
- "For the responsive design - are there specific breakpoint requirements?"
- "What authentication method should be used for this feature?"
- "Are there specific performance or accessibility requirements?"

## Process

1. **Extract Issue Information**

   - Parse the GitHub issue URL to get owner, repo, and issue number
   - Fetch the current issue content using GitHub MCP
   - Preserve the original issue description

2. **Analyze Issue for Completeness**

   - Analyze the original issue description for specificity and completeness
   - **CRITICAL: Identify missing or unclear information**
   - Check for gaps in user interactions, data sources, validation rules, etc.
   - **If information is missing: STOP and ask specific clarifying questions**
   - Only proceed once all necessary details are clarified

3. **Enhance Issue Content (Only After Clarification)**

   - Transform vague requirements into specific, comprehensive descriptions
   - Research the codebase for relevant patterns and examples
   - Identify documentation and resources needed for implementation
   - Determine project-specific constraints and potential pitfalls

4. **Create Context Engineering Format**

   - Add a comment to the GitHub issue with the enhanced, formatted content
   - Use the INITIAL.md structure with best practices:
     - **FEATURE**: Specific, comprehensive functionality description (not vague)
     - **EXAMPLES**: Concrete file references from examples/ and existing codebase
     - **DOCUMENTATION**: Complete list of URLs for APIs, libraries, guides
     - **OTHER CONSIDERATIONS**: Authentication, performance, pitfalls, constraints

5. **GitHub MCP Integration**
   - Use the GitHub MCP server to add a formatted comment to the issue
   - Preserve original content by keeping it intact in the issue description
   - The formatted comment becomes the context engineering specification

## Implementation Steps

1. **Parse Issue URL**

   ```
   Extract: owner, repo, issue_number from URL pattern:
   https://github.com/{owner}/{repo}/issues/{issue_number}
   ```

2. **Fetch Issue Content**

   ```
   Use GitHub MCP to get issue title and body content
   ```

3. **Generate Formatted Comment**

   ```
   Create a comment with this template following INITIAL.md best practices:

   ---
   # Context Engineering Specification

   ## FEATURE
   **Transform the original issue description to be specific and comprehensive:**

   ❌ Avoid: Vague descriptions like "Build a contact form"
   ✅ Provide: "Build an async contact form component for Astro.js that validates email/phone fields using Zod schemas, integrates with Cloudflare Workers for submission processing, handles spam protection with Turnstile, and provides real-time validation feedback with accessible error messages"

   **Requirements:**
   - Include specific technologies and libraries to be used
   - Define exact functionality and behavior
   - Specify integration points with existing REWOS architecture
   - Detail validation, error handling, and user experience requirements

   ## EXAMPLES
   **Leverage the examples/ folder and existing codebase patterns:**

   - **Specific file references:** `examples/[relevant-pattern]/[file].tsx`
   - **Existing components to follow:** `astro/src/components/[ComponentName]/`
   - **Pattern explanations:** What aspects should be mimicked (styling, validation, state management)
   - **Architecture patterns:** Reference similar implementations in the codebase

   **Example format:**
   ```

   Follow the pattern established in:

   - `astro/src/components/ContactForm.astro` for form structure
   - `examples/form-validation/zod-schema.ts` for validation patterns
   - `astro/src/utils/component-to-html.ts` for HTML generation patterns

   ```

   ## DOCUMENTATION
   **Include ALL relevant resources with specific URLs:**

   - **API Documentation:** Direct links to relevant API sections
   - **Library Guides:** Astro.js, React, Zod, Cloudflare Workers documentation
   - **MCP Server Documentation:** If using GitHub, Playwright, or other MCP servers
   - **Database Schemas:** Strapi content type definitions
   - **Deployment Docs:** Cloudflare Pages/Workers specific documentation

   **Example format:**
   ```

   - Astro Forms: https://docs.astro.build/en/guides/server-side-rendering/#form-actions
   - Zod Validation: https://zod.dev/?id=basic-usage
   - Cloudflare Workers: https://developers.cloudflare.com/workers/runtime-apis/request/
   - Strapi API: https://docs.strapi.io/dev-docs/api/rest

   ```

   ## OTHER CONSIDERATIONS
   **Capture important implementation details:**

   - **Authentication Requirements:** API keys, user sessions, permissions
   - **Rate Limits/Quotas:** Cloudflare Workers limits, API rate limits
   - **Common Pitfalls:** REWOS-specific gotchas that AI agents commonly miss
   - **Performance Requirements:** Bundle size, loading time, Core Web Vitals impact
   - **Browser Compatibility:** Specific browser support requirements
   - **Accessibility:** WCAG compliance, screen reader support
   - **Responsive Design:** Breakpoint-specific behavior, container queries usage
   - **Integration Constraints:** How this affects existing Astro/Strapi integration

   **Example format:**
   ```

   - Cloudflare Workers have 10ms CPU time limit for form processing
   - Must use CSS container queries (not viewport queries) for responsive behavior
   - REWOS project requires Lighthouse score >95 - optimize for Core Web Vitals
   - Form validation must work without JavaScript (progressive enhancement)
   - Spam protection: Use Turnstile, not reCAPTCHA (brand consistency)

   ```

   ---
   *This comment contains the context engineering specification for this feature following INITIAL.md best practices.*
   ```

4. **Add Comment to Issue**
   ```
   Use GitHub MCP to post the formatted comment to the issue
   ```

## Expected Outcome

### If Issue Has Complete Information:

- Original issue description remains unchanged
- New comment contains the INITIAL.md formatted specification
- Comment can be referenced by the `generate-prp` command
- Workflow can proceed with GitHub issue as the source of truth

### If Issue Has Missing Information:

- **Command pauses and asks for clarification** with specific questions
- User provides missing details in response
- **Only then** proceeds to create the formatted comment
- Ensures comprehensive context before moving to PRP generation

**Key Principle**: Better to ask questions upfront than implement based on assumptions.

## Error Handling

- Validate GitHub URL format
- Check if issue exists and is accessible
- Handle authentication errors gracefully
- Provide clear feedback if formatting fails

## Usage Example

```
/initial-github-issue https://github.com/owner/repo/issues/123
```

This will fetch issue #123, analyze its content, and add a formatted comment following the context engineering principles.

## Additional instructions

Use sequential thinking, context7 MCPs to solve the problem using latest documentation and best practices. Ultrathink the approach and a plan.