Code Research Crafter

Code Research Crafter

Craft comprehensive research proposals from code analysis to GitHub RFC publication.

Workflow

Phase 1: Problem Discovery & Code Analysis

1. Ask the user for the target codebase (URL or local path) and the research topic. If neither is provided, do not proceed — ask the user to clarify. 2. Map the project structure: use glob **/*.{ts,js,py,go,rs,java} based on the detected language. Read README.md, CONTRIBUTING.md, and docs in docs/ for context. 3. Search for topic-relevant files: grep "[keyword]" src/** to locate key implementations. 4. Read the top relevant files and document findings in research-context.md: - Code Map: file paths and their roles (table format) - Problem List: each problem with file:line reference and severity (high/medium/low) - Metrics: quantified issues (e.g., "3/10 modules lack error handling", "40% of functions have no tests") 5. Search existing GitHub issues: gh issue list -R [repo] --search "[topic]" --limit 20.

Error handling: If the codebase is inaccessible, ask for an alternative URL or local path. If the topic is too broad, narrow down with the user before proceeding.

Phase 2: Academic & Community Research

1. Load references/academic-research-guide.md for search methodology. 2. Use WebSearch for academic papers: "site:arxiv.org [topic] 2024 2025", "site:scholar.google.com [topic]". 3. Use WebFetch to read top 3-5 relevant papers and extract: algorithms, data structures, evaluation methods. 4. Search GitHub discussions: gh api repos/[owner]/[repo]/discussions --jq '.[].title' (if discussions are enabled). 5. Analyze community sentiment from issues: note pain points, feature requests, and maintainer feedback patterns. 6. Append findings to research-context.md under sections: - Academic Insights: algorithms, approaches, evaluation metrics - Community Pulse: top pain points, requested features, maintainer stance - Gaps: current implementation vs. best practices

Error handling: If no academic papers are found, note the gap and proceed with community research only. If the repo has no issues/discussions, focus on academic research and documentation review.

Phase 3: Solution Design

1. Load references/architecture-patterns.md for proven design patterns. 2. Define evidence-based design principles derived from Phase 1-2 findings. 3. Design a layered architecture: - Layer 1 — Foundation: data collection and storage - Layer 2 — Enhancement: core features building on Foundation - Layer 3 — Intelligence: AI/ML capabilities on accumulated data - Layer 4 — Governance: control, monitoring, and policy enforcement 4. Define data models: dual-track (user-defined/static + system-learned/dynamic). 5. Plan phased implementation with milestones: - Phase 1 → Foundation (weeks 1-4) - Phase 2 → Enhancement (weeks 5-8) - Phase 3 → Intelligence (weeks 9-12) - Phase 4 → Governance (weeks 13-16) 6. Document trade-offs: migration path, backward compatibility, performance cost, risk assessment.

Checkpoint: Present the proposed solution design to the user. Wait for approval before proceeding. If the user requests changes, iterate on the design and re-present.

Phase 4: Documentation Generation

1. Determine language needs: - If the target project's primary language is Chinese → generate bilingual (Chinese + English) documents - If the target project is international → generate English-only documents - Always generate the RFC in English (the lingua franca of open source) 2. Generate a structured technical document using python-docx (if available) or markdown: - Include: table of contents, numbered headings, citations, references section - Use consistent terminology throughout - Save as proposal.md (and proposal.docx if python-docx is available)

Phase 5: RFC Writing

1. Load references/rfc-template.md for the standard RFC template. 2. Write the RFC in English with these required sections:

   # RFC: [Title]
   ## Metadata
   - Author: [name]
   - Date: [YYYY-MM-DD]
   - Status: Draft
   - Related Issues: #[issue numbers]
   ## Problem Statement
   [Quantified problem with code evidence and metrics]
   ## Prior Art
   [Academic research, existing solutions, and community context]
   ## Proposed Solution
   [Architecture, data models, API design, implementation phases]
   ## Trade-offs
   [Cost analysis, migration path, backward compatibility, risks]
   ## Open Questions
   [Unresolved decisions needing community input]
   ## Call for Collaboration
   [How to get involved, what help is needed]
   

Phase 6: GitHub Publication

1. Check authentication: gh auth status. If not authenticated, provide setup instructions and ask the user to configure. 2. Save the RFC as rfc-[slug].md in the project's docs/ or proposals/ directory. 3. Create a GitHub issue:

   gh issue create -R [owner]/[repo] \
     --title "RFC: [Title]" \
     --body-file rfc-[slug].md \
     --label "enhancement" --label "RFC"
   

   curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
     https://api.github.com/repos/[owner]/[repo]/issues \
     -d '{"title":"RFC: [Title]","body":"[RFC content]","labels":["enhancement","RFC"]}'
   

Output Artifacts

| Artifact | Format | Description | |----------|--------|-------------| | research-context.md | Markdown | Running document updated through Phases 1-3 | | proposal.md / proposal.docx | MD/DOCX | Structured technical document | | rfc-[slug].md | Markdown | RFC in standard format | | GitHub Issue | Web | Link to published RFC |

Best Practices

1. Quote specific code locations — always reference file paths and line numbers 2. Quantify problems — use metrics like "50% of files" or "3x performance improvement" 3. Cite recent research — prefer papers from 2024-2025 4. Design for adoption — include migration paths and gradual rollout plans 5. Track costs — document token usage, performance implications, and resource requirements 6. Engage early — reference existing issues and invite collaboration from the start 7. Self-review citations — verify every claim has a code location or paper reference

1. Quote specific code locations — always reference file paths and line numbers 2. Quantify problems — use metrics like "50% of files" or "3x performance improvement" 3. Cite recent research — prefer papers from 2024-2025 4. Design for adoption — include migration paths and gradual rollout plans 5. Track costs — document token usage, performance implications, and resource requirements 6. Engage early — reference existing issues and invite collaboration from the start 7. Self-review citations — verify every claim has a code location or paper reference