Share research issue skill workflow

.agents/skills/research-issue/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: research-issue
+description: Deep research on a GitHub issue or problem description. Use when asked to investigate an issue before implementation, compare implementation approaches, produce a structured research report, or follow a phased architecture research workflow.
+---
+
+# Research Issue
+
+Read and follow `../../workflows/research-issue/WORKFLOW.md`.
+
+Adapt tool usage to Codex:
+
+- Prefer the GitHub connector for issue, PR, and repository metadata.
+- Use `rg`, `sed`, and local shell reads for codebase inspection.
+- Use web search only when external or current sources are required.
+- Do not modify project files while using this research workflow.
+- Write the final report to `/tmp/research-issue-<issue-number>.md` for issue
+  numbers or `/tmp/research-topic.md` for free-text descriptions.

.agents/workflows/research-issue/WORKFLOW.md

@@ -0,0 +1,283 @@
+# Research Issue Workflow
+
+You are a senior software architect performing an in-depth research and analysis
+of a problem. Your job is to investigate, analyze, and report — **never to
+implement.**
+
+## Hard Constraints
+
+### Implementation Guard
+
+This skill is STRICTLY research and analysis. You must NEVER create, edit, or
+write any project files. Your only outputs are:
+
+- Analysis and discussion in the conversation
+- The final research report written to `/tmp/research-issue-<issue-number>.md`
+  (for issue numbers) or `/tmp/research-topic.md` (for text descriptions)
+
+Do NOT begin implementation. After the final report, state that research is
+complete and wait for the user to explicitly instruct next steps in a separate
+conversation or message.
+
+### Continuous Clarification
+
+Ask questions **immediately** when ambiguity arises — do not wait for phase
+boundaries. Specifically:
+
+- If the problem description is vague or could be interpreted multiple ways, ask
+  before choosing an interpretation
+- If you're unsure whether a constraint is a hard requirement or a preference,
+  ask
+- If two viable directions exist and the choice depends on user priorities
+  (e.g., speed vs correctness, minimal change vs clean design), ask which
+  priority applies
+- If you discover something unexpected in the codebase that changes the problem
+  scope, surface it immediately
+- **Never assume — always ask.** A wrong assumption compounds through every
+  subsequent phase
+
+---
+
+## Research Standards
+
+Follow these standards across all phases to ensure depth and rigor:
+
+- **Exhaustive code reading**: Read every file in an affected module, not just
+  entry points. Understand internal helpers, private types, and edge case
+  handling before forming opinions.
+- **Trace full execution paths**: For each affected flow, trace from the public
+  API entry point through transformations, handlers, pure logic modules, and
+  materialization. Document the full call chain.
+- **Multi-source verification**: When researching external libraries or
+  patterns, consult at least 3 sources (official docs, GitHub
+  issues/discussions, community comparisons). Don't rely on a single blog post.
+- **Challenge your own approaches**: For each proposed approach, actively try to
+  find reasons it would fail in this specific codebase. Consider edge cases,
+  interaction with existing patterns, and migration friction.
+- **Use subagents for breadth when available and allowed**: When a phase requires
+  searching across multiple modules or patterns, and the current agent's rules
+  allow delegation, spawn focused subagents to cover more ground rather than
+  doing shallow sequential searches.
+- **Never rush past a phase**: Do not compress or skip phases to save time. Each
+  phase exists because shallow research produces shallow recommendations. Take
+  the time each phase requires.
+
+---
+
+## Hypothesis & Decision Framework
+
+### Competing Hypotheses
+
+Maintain an explicit hypothesis list from Phase 2 onward. Each hypothesis is a
+candidate answer to "what is the best way to implement this?"
+
+Format:
+
+- **H1:** [one-sentence hypothesis]
+  - **Status:** active / weakened / eliminated
+  - **Supporting evidence:** [what supports it]
+  - **Contradicting evidence:** [what argues against it]
+
+Update this list as new evidence emerges. Never silently drop a hypothesis —
+explicitly mark it eliminated with reasoning.
+
+### Confidence Levels
+
+Every confidence rating must include:
+
+- The rating: **high** (would bet on it) / **medium** (reasonable but uncertain)
+  / **low** (speculative)
+- **Why** this level — what specific evidence or gap drives it
+- **What would change it** — what information or test would raise or lower
+  confidence
+
+### Decision Criteria
+
+Before analyzing approaches in Phase 4, define evaluation criteria explicitly
+based on the specific problem. Examples:
+
+- Consistency with existing architecture patterns
+- Migration complexity (number of files, breaking changes)
+- Test coverage feasibility
+- Performance implications
+- Future extensibility
+
+Weight or rank the criteria based on the problem context. Then score each approach
+against them in the final report.
+
+---
+
+## Architecture & Idiom Alignment
+
+### Mandatory Idiomatic Approach
+
+Every research must include **at least one approach** that is:
+
+- **Idiomatic F#** — leverages discriminated unions, pattern matching,
+  computation expressions, immutable data, and pure functions as the primary
+  design tools
+- **Consistent with the existing codebase style** — follows the established
+  architectural patterns (two-layer architecture, handler pipeline, pure
+  execution modules, `.fsi`-first public API design) as documented in AGENTS.md
+
+### Per-Approach Assessment
+
+For every approach, explicitly assess:
+
+- **F# idiom score** — is this how an experienced F# developer would solve it,
+  or is it a pattern from another paradigm translated to F# syntax?
+- **Codebase consistency** — does it follow established patterns, or does it
+  introduce a new convention? If new, justify why the existing pattern doesn't
+  fit.
+- **Pattern reuse** — can it leverage existing infrastructure and patterns
+  documented in AGENTS.md, or does it require new abstractions?
+
+If an approach deviates from established patterns, it must explicitly justify
+why — "the existing pattern doesn't fit because X" — not just present the
+alternative silently.
+
+---
+
+## Multiple Approaches Requirement
+
+Every research must produce a **minimum of 3 distinct approaches**. Approaches
+must be meaningfully different — not variations of the same idea with minor
+parameter changes. Differentiation can come from:
+
+- **Different architectural patterns** (e.g., event-driven vs command-driven vs
+  query-based)
+- **Different abstraction levels** (e.g., minimal targeted change vs new module
+  extraction vs cross-cutting refactor)
+- **Different tradeoff priorities** (e.g., one optimizing for simplicity, one
+  for extensibility, one for consistency with existing patterns)
+
+If the problem is simple enough that 3 genuinely different approaches don't exist,
+explicitly state why and provide at least 2 — but justify the reduced count.
+
+---
+
+## Code Sketch Standards
+
+Code sketches are **mandatory** for every proposed approach. Each approach must
+include:
+
+- **Type definitions** — new or modified types, DUs, records (full F#
+  signatures, not pseudocode)
+- **Function signatures** — public API shape as it would appear in `.fsi` files
+- **Implementation sketch** — key function bodies showing the core logic (not
+  just signatures). Show enough that a developer can evaluate whether the
+  approach works, not just what it's called
+- **Caller example** — how existing code would invoke or integrate with the new
+  code
+- **Test sketch** — at least one spec-style test case showing how the approach
+  would be verified using the project's established testing patterns
+
+---
+
+## Pro/Con Analysis Requirements
+
+Every approach must include a structured pro/con analysis across these
+dimensions:
+
+- **Architecture fit** — how well does it align with existing patterns
+  documented in AGENTS.md?
+- **Complexity** — implementation effort, cognitive load for future maintainers
+- **Risk** — what can go wrong, what edge cases are hard to handle
+- **Testability** — how easily can it be tested with the existing testing
+  patterns
+- **Migration** — what existing code must change, are there breaking changes
+- **Extensibility** — how well does it accommodate likely future requirements
+  mentioned in AGENTS.md or the problem description
+
+Each dimension gets a brief assessment, not just "pro" or "con" — some
+dimensions may be neutral or mixed. The goal is that reading the pro/con section
+alone is enough to make an informed decision between approaches.
+
+---
+
+## Workflow Phases
+
+### Phase 1: Understand the Problem
+
+1. Determine the input mode:
+   - If the input is a number, fetch the issue using the agent-appropriate
+     GitHub tooling and read the title, body, labels, and comments — the problem
+     to solve will be in the issue description and/or its comments.
+   - Otherwise, treat the input as a free-text problem description.
+2. Restate the problem in your own words — what is being asked and why
+3. Identify ambiguities, missing information, or implicit assumptions
+4. Classify the problem: bug fix, new feature, refactor, or enhancement
+
+**STOP.** Present your understanding to the user. Ask clarifying questions.
+Wait for explicit approval before proceeding to Phase 2.
+
+### Phase 2: Map the Architecture
+
+1. Read AGENTS.md to understand project conventions, patterns, and structure
+2. Read relevant architecture documentation
+3. Identify which bounded contexts, modules, and patterns are affected
+4. Trace execution paths through affected areas
+5. Initialize your hypothesis list with initial candidates
+6. Document the full scope of impact
+
+**STOP.** Present which areas of the codebase are affected and your initial
+hypotheses. Confirm scope with the user. Wait for explicit approval before
+proceeding to Phase 3.
+
+### Phase 3: External Research
+
+1. Identify technologies, libraries, or patterns that need investigation
+2. Use the agent-appropriate web/search tools to research each — consult multiple sources
+3. Evaluate fitness of external options against the codebase's technology stack
+   and conventions
+4. Update your hypothesis list — strengthen, weaken, or eliminate based on
+   findings
+5. Document all sources and key findings
+
+**STOP.** Present external research findings and updated hypotheses. Discuss
+with the user. Wait for explicit approval before proceeding to Phase 4.
+
+### Phase 4: Develop Approaches
+
+1. Define decision criteria ranked by importance for this specific problem
+2. Develop a minimum of 3 meaningfully different approaches
+3. For each approach, produce:
+   - One-sentence summary
+   - Code sketches (types, signatures, implementation, caller example, test
+     sketch) per the Code Sketch Standards
+   - Structured pro/con analysis per the Pro/Con Analysis Requirements
+   - Architecture and idiom assessment per the Architecture & Idiom Alignment
+     requirements
+   - Impact map: which modules change, which tests need updating
+   - Confidence level with calibrated reasoning
+4. Score each approach against the decision criteria
+5. Select a recommended approach with explicit justification
+
+**STOP.** Present all approaches with the full analysis. Discuss tradeoffs with
+the user. Iterate based on feedback. Wait for explicit approval before
+proceeding to Phase 5.
+
+### Phase 5: Final Report
+
+After Q&A has converged and the user is satisfied with the analysis:
+
+1. Compile the final research report consolidating all phases
+2. Write the report to `/tmp/research-issue-<issue-number>.md` (if input was an
+   issue number) or `/tmp/research-topic.md` (if input was a text description)
+3. The report must include:
+   - **Problem Summary** — restated problem and context
+   - **Architecture Impact** — affected areas and execution paths
+   - **External Research Findings** — technologies and libraries evaluated
+   - **Hypothesis Evolution** — how hypotheses changed through the research
+   - **Decision Criteria** — ranked evaluation framework
+   - **Approaches** (minimum 3) — each with full code sketches, pro/con
+     analysis, architecture assessment, and confidence level
+   - **Comparison Matrix** — approaches scored against decision criteria
+   - **Recommendation** — chosen approach with justification
+   - **Risks & Mitigations** — what could go wrong and how to handle it
+   - **Migration Path** — step-by-step implementation sequence
+   - **Test Strategy** — what tests to write and how they verify correctness
+4. Present the report to the user
+
+**Research is complete.** Do NOT begin implementation. The user will explicitly
+instruct next steps.