Create Issue With Websearch

topic = the user's request

Use this skill when the user only has a rough, fuzzy idea and needs heavy web research to clarify the target specification before creating an issue. If the user already has a concrete, well-scoped task in mind, use the create-issue skill instead.

Step 1: Gather the Initial Idea

Receive the topic from topic or the user's description.

If the input is very sparse, ask the user just enough to anchor the research:

• What is the rough area or goal? (e.g., a tool to support, a feature to add, a behavior to change)
• Why do they want it — what problem or limitation triggered the idea?
• Any hard constraints known up front (must/must-not, scope boundaries)?

Do not push for full specification details at this stage. The point of this skill is to resolve the unknowns through research, not to force the user to resolve them manually.

Step 2: Research the Topic on the Web

Investigate the topic thoroughly using WebSearch and WebFetch. The goal is to raise the resolution of the specification until concrete, defensible design decisions become possible.

Look for, as applicable to the topic:

• Official documentation of any tool, standard, protocol, or API involved — prefer primary sources over blog posts.
• File formats, configuration schemas, naming conventions, and default locations used by the target tool(s).
• Feature support matrices: project vs. global scope, supported file types, known limitations.
• Recent changes, deprecations, or pre-release behavior that might affect the design.
• Prior art: how similar tools or competing implementations solve the same problem.
• Existing discussions (GitHub issues, release notes, RFCs) that reveal open questions or community expectations.

Guidelines while researching:

• Run multiple searches in parallel when the angles are independent.
• Cross-check claims against at least one primary source before relying on them.
• Capture exact URLs, version numbers, and quoted snippets as you go — they will be cited in the issue.
• If a source disagrees with another, note the disagreement explicitly rather than silently picking one side.
• Stop expanding research once the open questions needed to draft the issue are answered; avoid rabbit holes unrelated to the decision.

Step 3: Research the Codebase

With the web findings in hand, investigate the relevant parts of this repository to ground the issue in the real code:

• Which files, modules, or conventions are affected?
• How do existing, analogous features handle the same concerns (scope, frontmatter, generated output, tests)?
• Which project-specific rules apply (see CLAUDE.md, .claude/rules/**, docs/**)?

Prefer targeted symbol and search tools over reading whole files.

Step 4: Synthesize the Specification

Before drafting, write down internally:

• The sharpened problem statement (one or two sentences).
• The concrete proposal — scope, interfaces, file layout, defaults — as resolved by the research.
• Open questions that research could not close, stated as explicit unknowns.
• Trade-offs and the reasoning behind the chosen direction.

If, after research, the idea still cannot be pinned down to an actionable proposal, stop and report this to the user instead of filing a vague issue.

Step 5: Draft the Issue

All issue content (title, body, labels) must be written in English, regardless of the conversation language.

Use this structure:

## Summary

A concise one-liner describing the sharpened proposal.

## Motivation / Purpose

The problem or opportunity, grounded in what the research revealed (user impact, missing capability, spec gap, etc.).

## Background from Research

Key findings from the web research that shape the proposal. Keep it tight, but every non-trivial factual claim must be backed by an inline link to its source (e.g., `[official docs](https://...)`). Include exact version numbers where relevant. Do not paraphrase a source without linking to it.

## Proposed Specification

The concrete plan the research supports:

- Behavior and scope (project / global, supported inputs, outputs)
- File formats, paths, frontmatter, and defaults
- Interactions with existing features in this repo
- Acceptance criteria / expected behavior

## Open Questions

Unresolved points that need a maintainer decision, each phrased as a concrete question with the options considered.

## References

Bulleted list of the primary sources used, with links.