\r \r

Code Research Crafter\r

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

Workflow\r

\r

Phase 1: Problem Discovery & Code Analysis\r

\r

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.\r
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.\r
3. Search for topic-relevant files: grep "[keyword]" src/** to locate key implementations.\r
4. Read the top relevant files and document findings in research-context.md:\r
   • Code Map: file paths and their roles (table format)\r
   • Problem List: each problem with file:line reference and severity (high/medium/low)\r
   • Metrics: quantified issues (e.g., "3/10 modules lack error handling", "40% of functions have no tests")\r
5. Search existing GitHub issues: gh issue list -R [repo] --search "[topic]" --limit 20.\r \r 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.\r \r

Phase 2: Academic & Community Research\r

\r

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

Phase 3: Solution Design\r

\r

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

Phase 4: Documentation Generation\r

\r

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

Phase 5: RFC Writing\r

\r

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

   # RFC: [Title]\r
   

\r

Metadata\r

• Author: [name]\r
• Date: [YYYY-MM-DD]\r
• Status: Draft\r
• Related Issues: #[issue numbers]\r \r

Problem Statement\r

[Quantified problem with code evidence and metrics]\r \r

Prior Art\r

[Academic research, existing solutions, and community context]\r \r

Proposed Solution\r

[Architecture, data models, API design, implementation phases]\r \r

Trade-offs\r

[Cost analysis, migration path, backward compatibility, risks]\r \r

Open Questions\r

[Unresolved decisions needing community input]\r \r

Call for Collaboration\r

[How to get involved, what help is needed]\r

3. Include code examples (with syntax highlighting) and ASCII architecture diagrams.\r
4. Reference specific GitHub issues and discussions using `#123` format.\r
5. Self-review: verify every claim has a citation (code location or paper reference).\r
\r
### Phase 6: GitHub Publication\r
\r
1. Check authentication: `gh auth status`. If not authenticated, provide setup instructions and ask the user to configure.\r
2. Save the RFC as `rfc-[slug].md` in the project's `docs/` or `proposals/` directory.\r
3. Create a GitHub issue:\r
```bash\r
gh issue create -R [owner]/[repo] \\r
  --title "RFC: [Title]" \\r
  --body-file rfc-[slug].md \\r
  --label "enhancement" --label "RFC"\r
```\r
4. If `gh` CLI is unavailable, try GitHub API via `curl`:\r
```bash\r
curl -X POST -H "Authorization: token $GITHUB_TOKEN" \\r
  https://api.github.com/repos/[owner]/[repo]/issues \\r
  -d '{"title":"RFC: [Title]","body":"[RFC content]","labels":["enhancement","RFC"]}'\r
```\r
5. If all CLI options fail, output the RFC markdown with manual submission instructions:\r
- URL to create issue: `https://github.com/[owner]/[repo]/issues/new`\r
- Suggested title and labels\r
- Full RFC content to paste\r
6. Reference related issues in the created issue body. Do NOT tag maintainers unless the user explicitly asks.\r
\r
## Output Artifacts\r
\r
| Artifact | Format | Description |\r
|----------|--------|-------------|\r
| `research-context.md` | Markdown | Running document updated through Phases 1-3 |\r
| `proposal.md` / `proposal.docx` | MD/DOCX | Structured technical document |\r
| `rfc-[slug].md` | Markdown | RFC in standard format |\r
| GitHub Issue | Web | Link to published RFC |\r
\r
## Best Practices\r
\r
1. **Quote specific code locations** — always reference file paths and line numbers\r
2. **Quantify problems** — use metrics like "50% of files" or "3x performance improvement"\r
3. **Cite recent research** — prefer papers from 2024-2025\r
4. **Design for adoption** — include migration paths and gradual rollout plans\r
5. **Track costs** — document token usage, performance implications, and resource requirements\r
6. **Engage early** — reference existing issues and invite collaboration from the start\r
7. **Self-review citations** — verify every claim has a code location or paper reference\r