Format GitHub Issue for Context Engineering

GitHub Issue URL: $ARGUMENTS

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

## 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.