JnBrymn/explain-in-issue.md Secret

## explain-in-issue.md

      
    Raw
  

              explain-in-issue.md
            
          
    Explain Issue Workflow

This command combines codebase explanation with GitHub issue creation, creating a structured explanation document and then transcribing it to a GitHub issue with linked detail sections.
Process Overview


Identify the type of explanation needed
Create an explanation directory in IGNORED/ (all caps) with separate markdown files for each section
Write a main summary file with top-level explanation linking to detail files
Write separate markdown files for each detail section/subsection
Create a GitHub issue and use comments for detail sections
Link everything together with inline markdown links

Step 0: Understand the Request and Verify Context

CRITICAL: Before proceeding with any explanation, you MUST fully understand what the user is asking for. This step is mandatory and cannot be skipped.
Phase 1: Initial Analysis

First, analyze the user's request to understand:

What exactly are they asking about? - Parse the request carefully for key terms, concepts, or technologies
Is this in the codebase or external? - Determine if the topic exists in the current repository or refers to external knowledge
Scope: Is this about a specific file, a process, a concept, or the entire codebase?
Purpose: Is this for understanding, debugging, learning, or documentation?
Depth: Does it need step-by-step detail or high-level overview?
Context: Does it require external knowledge (libraries, frameworks, concepts)?

Phase 2: Research and Verification

For any request, especially those mentioning external technologies, libraries, or concepts:


Search the web first - Use web_search to understand what the user is referring to:

If they mention a technology/library name (e.g., "Google ADK", "React hooks", "TensorFlow"), search for current documentation and understanding
Verify what the technology actually is and its current state
Check if there are multiple meanings or if it's commonly confused with something else


Search the codebase - Use codebase_search and grep to see if the topic exists in the repository:

If found in codebase: Proceed with codebase-focused explanation
If NOT found in codebase: This likely requires external knowledge or clarification


Cross-reference findings:

Compare what you found in web search vs codebase search
If they don't align (e.g., web search shows "Google ADK" is Android Development Kit, but codebase has Google GenAI SDK), this is a mismatch that needs clarification


Phase 3: Clarification Check

If any of the following conditions are true, you MUST ask the user for clarification before proceeding:

The request mentions something that doesn't exist in the codebase AND you're uncertain if it should
Web search reveals the term has multiple meanings or could be confused with something else
The codebase has something with a similar name but different purpose (e.g., "Google ADK" vs "Google GenAI SDK")
You cannot confidently determine what the user wants explained
The request is ambiguous or could be interpreted multiple ways

Clarification format:
I found [X] in the codebase, but your request mentions [Y]. Based on my research:
- [X] is [description of what's in codebase]
- [Y] typically refers to [description from web search]

Could you clarify:
1. Do you want an explanation of [X] from the codebase?
2. Or do you want a tutorial/guide about [Y] (which isn't in this codebase)?
3. Or something else?

DO NOT proceed with creating an explanation until you have clarity. It's better to ask one clarifying question than to create an incorrect explanation.
Phase 4: Proceed with Understanding

Once you have clarity (either from research or user clarification), proceed to identify the explanation type and continue with the workflow.
Common Explanation Types (Examples)

These are examples of common requests, not an exhaustive list:

File/Code Explanation: Understanding how specific code works
Process/Dataflow: Tracing how something moves through the system
Library/Framework Usage: How external tools are integrated
Architecture/Structure: How code is organized and connected
Bug/Issue: Explaining problems and solutions
Tutorial/Guide: Learning-focused explanations

Adapting the Approach

For code-focused explanations:

Focus on structure, functions, relationships, and flow
CRITICAL: Link to specific code locations extensively - whenever you mention a function, class, variable, or operation, link it to where it's defined or used
Link function and class names directly in the text to their definitions (e.g., "The processData function handles...")
Explain entry points and control flow with inline links
Document key data structures with links to their definitions
Whenever discussing specific lines or sections of code, embed links naturally in the narrative text

For process-focused explanations:

Start from entry points (API, file, user input) with links to those locations
Follow transformations step-by-step, linking each transformation to the relevant code
Show where things are stored, modified, or consumed with inline links (e.g., "Data is stored in the database after validation")
Use sequential lists or flow descriptions with embedded code links throughout
Link function calls, API endpoints, and data operations naturally in the text

For external knowledge (libraries, frameworks, concepts):

CRITICAL: This should have been identified in Step 0 Phase 2 - if you're here and the topic isn't in the codebase, verify the user wants an external tutorial/guide
Search the web and API documentation for up-to-date knowledge
Use web_search tool to find current best practices, examples, and documentation
Use available MCP servers for library-specific documentation (check list_mcp_resources to see what's available)
CRITICAL: Source Attribution - When sourcing content from online, use inline ([ref](url)) format:

Use the exact format ([ref](url)) - same pattern as ([details](url)) for subsections
Link to specific source URLs with hash anchors when available (e.g., ([ref](https://docs.example.com/guide#section-name)))
Place references inline where the information appears, not in a separate section
Make it clear where each piece of information came from


If creating a tutorial about external technology, clearly state this is a general guide, not codebase-specific
Note version compatibility and deprecation warnings

For learning/tutorial explanations:

Structure as a learning guide with examples
Combine concepts with codebase examples
Include step-by-step walkthroughs
Provide context and background information

The key is to understand the user's intent and adapt the explanation structure accordingly.
Step 1: Create Explanation Directory Structure

Directory Naming


Pattern: IGNORED/<explanation_name>/
Use descriptive names based on the topic being explained
Example: IGNORED/training-algorithm-summary/

Directory Structure

Create a directory and organize files as follows:
Main Summary File


Create README.md (or summary.md) in the explanation directory
Write the main explanation with inline links to detail files
Use terse numbered/bullet lists for high-level flow
Keep main points concise and scannable
Use descriptive variable names in parentheses: (variable_name)
Link to detail files inline using the exact format: ([details](./detail-file-name.md)) (you will create these files next)
Critical: The link text must be exactly ([details](<link>) - do not change the text "details" or the parentheses/brackets format
Example: "Split by data_split into train (train_df) and test (test_df) sets (details)."
All detail links should be inlined appropriately in the higher-level explanation - do not create a separate section for all detail links

Detail Section Files


Create a separate markdown file for each detail section/subsection
Use descriptive filenames based on the section content (e.g., data-splitting.md, implementation.md, error-handling.md)
Each file should contain full markdown content
Use proper markdown headings (##, ###, etc.)
Include all code references with GitHub links
Include source links for external content: When information comes from online sources, link to the specific source with hash anchors when available
Structure each as complete, standalone content
Example file data-splitting.md:

# Data Splitting Details

This section explains how data splitting works...

## Implementation
- [Load data from S3](https://github.com/org/repo/blob/hash/file.py#L123)
- [Split logic](https://github.com/org/repo/blob/hash/file.py#L456)

The splitting algorithm uses consistent hashing to distribute data evenly ([ref](https://docs.example.com/algorithms#consistent-hashing)). Best practices for data distribution are documented here ([ref](https://guide.example.com/data-splitting#implementation)).
File Organization


Write as many detail files as needed
Use clear, descriptive filenames that match the section names
For nested details (rare), create subdirectories or use descriptive filenames like data-splitting-validation.md
The main summary file (README.md) serves as the entry point with links to all detail files

Code References and Links

Get the current commit hash:

git rev-parse HEAD
Check if repository is on GitHub:


Look for .git/config or check remote URLs
If not on GitHub, ask user to add it
If on GitHub, construct URLs using format:
https://github.com/{org}/{repo}/blob/{hash}/{file_path}#L{line_number}


Add links to everything - be comprehensive:


CRITICAL: Link extensively throughout the explanation - whenever you discuss code, link it
Link all code references to specific line numbers in the URL (e.g., #L13-L14), but do not mention line numbers in the text
Use inline links naturally embedded in descriptive text: [set at image build time](url) not ([lines 13-14](url))
Example: "Job-specific values (JOB_ID, TRAINING_DATA_URL) come from environment variables set at image build time."
Always link function and class names to their definitions whenever mentioned (e.g., "The processRequest function handles...", "The UserService class manages...")
Link variable references, key operations, API endpoints, and data transformations naturally in the text
When discussing specific lines or sections of code, embed links in the narrative: "And then data is sent to the backend" not "(lines 45-76)"
Link function calls to where they're called from, not just where they're defined
Link imports, exports, and module references
Include links in both top-level explanation and detail sections - be thorough
If you mention a file, function, class, variable, or code operation, it should have a link

Example Directory Structure

The structure adapts to the type of explanation needed. Here's a generic example:
IGNORED/explanation-name/
├── README.md          # Main summary with links to detail files
├── data-splitting.md  # Detail section file
├── implementation.md   # Detail section file
└── error-handling.md  # Detail section file

README.md (main summary):
# Explanation Title

## Overview

[High-level summary of what is being explained with inline code links]
- The [`processRequest` function](url) [handles incoming data](url) and [validates input](url) before [passing it to the transformer](url) ([details](./detail-section-name.md))
- Results are [stored via the `saveResults` method](url) after [transformation completes](url) ([details](./another-detail.md))

[Additional overview content with inline code links throughout, linking functions, classes, and operations naturally in the text]
detail-section-name.md (example detail file):
# Detail Section Name

[Full markdown content for this detail section with inline code links throughout]

## Subsection
The [`processData` function](url) [handles incoming requests](url) by first [validating the input](url), then [transforming the data](url) using the [`DataTransformer` class](url). After processing, results are [stored in the database](url) via the [`saveResults` method](url).

## Another Subsection
When errors occur, the [`ErrorHandler` class](url) [catches exceptions](url) and [logs them appropriately](url) ([ref](https://docs.example.com/error-handling#logging)). The error handling flow [starts here](url) and [continues through validation](url).
Note: The actual structure will vary based on the explanation type:

File explanations: Focus on file structure, functions, and flow
Dataflow: Sequential steps showing data transformation
Library usage: Usage patterns, key functions, integration points
Modularization: Module structure, dependencies, interfaces
Tutorials: Learning-focused with examples from codebase and external references
etc.

Step 2: Create GitHub Issue

Get Repository Information

gh repo view --json nameWithOwner -q .nameWithOwner
Create the Issue

gh issue create --title "<Issue Title>" --body-file IGNORED/explanation-name/README.md

Save the issue URL from the output
The output format is: https://github.com/{org}/{repo}/issues/{number}
Note: You can create with a temporary initial description file, then update it later with the final README.md

Create Comment Sections for Details

For each detail file in the explanation directory:


Create a comment directly from the detail file:
gh issue comment {issue_number} --body-file IGNORED/explanation-name/detail-file.md


Capture the comment URL from the output

Output format: https://github.com/{org}/{repo}/issues/{number}#issuecomment-{id}
Save these URLs for later linking
Map each URL to its corresponding detail file name


Alternative: Retrieve Comment URLs Programmatically

If you need to get comment URLs after creation:
gh api repos/{org}/{repo}/issues/{issue_number}/comments --jq '.[-1] | "\(.html_url)"'
Step 3: Link Everything Together

Update Issue Description

Edit the issue description to include inline links to the detail comments:
Important: Do not include any meta-mentions about GitHub issues in the README.md or detail files (e.g., "This GitHub issue...", "See this issue for..."). The content should be written as if it's standalone documentation, not referencing that it's in a GitHub issue.
First, update the README.md to replace file links with GitHub comment URLs:

Replace ([details](./detail-file.md)) with ([details](https://github.com/{org}/{repo}/issues/{number}#issuecomment-{id}))
Critical: The link text must remain exactly ([details](<link>) - only the URL changes, not the link text
Keep all detail links inline in the higher-level explanation - do not create a separate section

Then update the issue:
gh issue edit {issue_number} --body-file IGNORED/explanation-name/README.md
The top-level explanation from README.md becomes the issue description with all file links replaced with GitHub comment URLs, maintaining inline detail links throughout.
Update Comments (if needed)

If you need to add links within comments, update the detail file first, then:
gh issue comment {comment_id} --body-file IGNORED/explanation-name/detail-file.md
Complete Workflow Summary


Step 0: Understand and Verify - MANDATORY FIRST STEP

Analyze the user's request carefully
Search the web to understand external technologies/concepts mentioned
Search the codebase to see if the topic exists
Cross-reference findings
If uncertain or finding mismatches, ask the user for clarification before proceeding
Only continue once you fully understand what needs to be explained


Identify explanation type - Determine what kind of explanation is needed (after Step 0)
Research phase (for tutorials/external knowledge, if not already done in Step 0):

Use web_search for current best practices and examples
Check available MCP servers using list_mcp_resources
Use MCP servers for library-specific documentation
Search for official docs, recent blog posts, Stack Overflow, and GitHub issues
Track sources - Save source URLs with hash anchors for inline ([ref](url)) references


Get git hash - git rev-parse HEAD
Create explanation directory - IGNORED/<explanation-name>/
Create README.md - Main summary with inline links to detail files

Use ([details](./detail-file.md)) format for all detail links
Critical: The link text must be exactly ([details](<link>) - do not change the text "details" or the parentheses/brackets format
Keep all detail links inline in the explanation, not in a separate section


Create detail files - Separate markdown file for each detail section/subsection

Use descriptive filenames (e.g., data-splitting.md, implementation.md)
Each file contains full markdown content with extensive inline code links
Link function names, class names, variables, and operations naturally throughout the text
Embed links in narrative descriptions (e.g., "Data is processed here") rather than using parenthetical line references
External source references: Use ([ref](url)) format inline where information appears, with hash anchors when available


Create GitHub issue - gh issue create
Create comment for each detail file - gh issue comment {issue_number} --body-file IGNORED/explanation-name/detail-file.md
Capture comment URLs - Save from command output, map to file names
Update README.md - Replace file links with GitHub comment URLs (keep inline)
Update issue description - gh issue edit {issue_number} --body-file IGNORED/explanation-name/README.md
Output issue URL to user - At the end of your conversation, provide only this markdown link with no other commentary: [Here is a link to the new explanation issue](https://github.com/{org}/{repo}/issues/{number})

Key Points


CRITICAL: Step 0 is mandatory - Always fully understand the request before proceeding. Research external concepts, verify against codebase, and ask for clarification if uncertain. Do not proceed with an explanation if you're not confident about what the user wants.
Directory structure: One directory per explanation, separate files for each section
Main summary: README.md with concise, scannable content with inline links to detail files
Detail files: One markdown file per detail section/subsection
GitHub comments: One comment per detail file, read directly from the file
Linking: Use inline markdown links throughout (file links in README, replaced with comment URLs)

Detail links: Use ([details](./detail-file.md)) format - link text must be exactly ([details](<link>)
External references: Use ([ref](url)) format - link text must be exactly ([ref](<link>)
All links should be inlined in the explanation, not in separate sections


Code references: Always link to specific line numbers in the GitHub URL (e.g., #L13-L14), but do not mention line numbers in the text - link descriptive text instead

Be comprehensive: Link function names, class names, variables, API endpoints, and operations whenever mentioned
Natural embedding: Embed links naturally in the narrative text (e.g., "Data is sent to the backend") rather than using parenthetical references (e.g., avoid "(lines 45-76)")
Link definitions: Always link function and class names to where they're defined
Link usage: Also link to where functions/classes are called or used when relevant
Be thorough: If you mention code, link it - aim for comprehensive linking throughout explanations


External source references: Use ([ref](url)) format inline where information appears

Link text must be exactly ([ref](<link>) - same pattern as ([details](<link>)
Use hash anchors when available (e.g., ([ref](https://docs.example.com/guide#section-name)))
Place references inline, not in separate sections


Variable names: Use parentheses format: (variable_name)
Final step: Output only this markdown link with no other commentary: [Here is a link to the new explanation issue](https://github.com/{org}/{repo}/issues/{number})

Notes


The gh issue comment command returns the comment URL directly, making it easy to capture
Issue descriptions and comments support GitHub Flavored Markdown
Comment URLs use anchor fragments (#issuecomment-{id}) to link directly to specific comments
Keep the IGNORED directory as the source of truth, with GitHub issue links added to README.md
Using separate files makes it easy to reference specific sections when creating GitHub comments
File names serve as clear references when writing the summary and creating links
No results found