diff --git a/.agents/skills/research-issue/SKILL.md b/.agents/skills/research-issue/SKILL.md new file mode 100644 index 0000000..42fb700 --- /dev/null +++ b/.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-.md` for issue + numbers or `/tmp/research-topic.md` for free-text descriptions. diff --git a/.agents/workflows/research-issue/WORKFLOW.md b/.agents/workflows/research-issue/WORKFLOW.md new file mode 100644 index 0000000..cc1fab6 --- /dev/null +++ b/.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-.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-.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. diff --git a/.claude/skills/research-issue/SKILL.md b/.claude/skills/research-issue/SKILL.md index 1731ef7..6a1046e 100644 --- a/.claude/skills/research-issue/SKILL.md +++ b/.claude/skills/research-issue/SKILL.md @@ -11,286 +11,11 @@ disable-model-invocation: true allowed-tools: Read, Write, Grep, Glob, Bash(gh issue view:*), Bash(gh api:*), Agent, WebSearch, WebFetch --- -# Research +# Research Issue -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.** +Read and follow `../../../.agents/workflows/research-issue/WORKFLOW.md`. -## 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-$ARGUMENTS.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 Explore subagents for breadth**: When a phase requires searching across - multiple modules or patterns, spawn Explore 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 `$ARGUMENTS` is a number, fetch the issue using - `gh issue view $ARGUMENTS --json title,body,labels,comments` and read the - title, body, labels, and comments — the problem to solve will be in the - issue description and/or its comments - - Otherwise, treat `$ARGUMENTS` 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 WebSearch and WebFetch 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-$ARGUMENTS.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. +Use `$ARGUMENTS` as the issue number or problem description. For GitHub issue +numbers, prefer `gh issue view $ARGUMENTS --json title,body,labels,comments`. +Write the final report to `/tmp/research-issue-$ARGUMENTS.md` for issue numbers +or `/tmp/research-topic.md` for free-text descriptions. diff --git a/AGENTS.md b/AGENTS.md index cf1b73e..f15d099 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -128,12 +128,15 @@ Last verified: 2026-05-05 - **Technology choices (terminal):** Terminal.Gui v2 (TUI framework with views, menu bars, keyboard/mouse support), direct function calls for in-process messaging. - **RondelView architecture:** Stateless `RondelCanvas` (zero mutable fields) reads from shared `RondelViewState` record with mutable fields (`CurrentGame`, `Selection`, `Positions`). `SelectionMode` record (`Nation` + `Space`) replaces separate selection tracking — single `Option` makes state transitions atomic. `SyncFocus()` method toggles canvas focus based on selection state. Navigation uses `RondelLayout.nextSpace`/`prevSpace` helpers. `onSpaceSelected: Space -> unit` callback replaces direct `RondelHost` dependency. Color scheme: Investor=teal, Import=orange, Production=grey, Maneuver=green, Taxation=yellow, Factory=blue. Emoji flags (🇦🇹🇫🇷🇩🇪🇬🇧🇮🇹🇷🇺) on nation abbreviations with `displayWidth` helper for correct terminal centering. -## Claude Code Skills +## Agent Skills ### research-issue -- **Location:** `.claude/skills/research-issue/SKILL.md` -- **Invoke:** `/research-issue ` +- **Canonical workflow:** `.agents/workflows/research-issue/WORKFLOW.md` +- **Claude wrapper:** `.claude/skills/research-issue/SKILL.md` +- **Codex repo skill wrapper:** `.agents/skills/research-issue/SKILL.md` +- **Invoke in Claude:** `/research-issue ` +- **Invoke in Codex:** ask for the `research-issue` skill or request in-depth issue research. - **Purpose:** In-depth research and analysis of a GitHub issue or free-text problem description before implementation. Produces a structured report with multiple competing approaches, code sketches, pro/con analysis, and architecture alignment assessment. - **Read-only:** The skill cannot modify project files — it only produces analysis and a research report at `/tmp/research-issue-{number}.md` or `/tmp/research-topic.md`. - **Interactive:** Runs inline with explicit pause points between phases for Q&A. Ask clarifying questions at any time.