abildtoft/kramme:research

Research

Investigate a bounded question against primary sources and preserve the answer as a cited Markdown artifact. The skill gathers source-backed facts; it does not decide what to build.

Arguments: "$ARGUMENTS"

Boundaries

• Does: Research a specific question using primary sources: official documentation, source code, specifications, standards, schemas, first-party APIs, release notes, or other owner-published source-of-truth artifacts.
• Does: Write one cited Markdown artifact whose substantive claims trace back to sources.
• Does: Surface conflicts, gaps, and unknowns explicitly.
• Does not: Implement changes, create Pull Requests, choose product or architecture direction, run broad secondary-source web searches, cite blogs or summaries as authority, or answer only in chat.

Workflow

1. Establish the research question

   • Treat $ARGUMENTS as the research question after removing supported options.
   • Recognize --output <path> as an explicit artifact path.
   • If no question is provided and no clear question can be inferred from the conversation, ask for one bounded research question.
   • If the user asks for implementation too, complete the research artifact first and hand the findings back to the implementation workflow.

2. Resolve the artifact path

   • Derive <slug> from the question by lowercasing it, replacing each run of non-alphanumeric characters with one hyphen, trimming leading and trailing hyphens, and limiting it to 80 characters. If the slug is empty, use research.
   • If --output <path> is provided, store it as the candidate path. Otherwise inspect the workspace for an existing research-note convention, such as .context/research/, docs/research/, research/, or similarly named prior research Markdown files. Use the clearest existing convention.
   • If no convention exists, use .context/research/<slug>.md as the candidate path.
   • Resolve the candidate path before writing. Treat relative paths as relative to the current working tree root when available, otherwise the current working directory.
   • Refuse to write outside the current working tree unless the user explicitly confirms the exact resolved path after being warned that it is outside the workspace.
   • If the target path already exists, do not overwrite silently. Read the existing file enough to identify it, then ask whether to overwrite it, update it as a refresh, write to the next available suffixed path such as <slug>-2.md, or abort.
   • If a parent path exists but is not a directory, stop with the exact path and filesystem issue.
   • Create the destination directory only after the resolved path is accepted.

3. Identify acceptable sources

   • Prefer sources in this order:
     1. User-provided primary material, local repository source, tests, schemas, configuration, specifications, and generated API references.
     2. Official documentation, standards, RFCs, source repositories, first-party API references, changelogs, and release notes.
     3. First-party issue trackers, discussions, or support articles only when they are the closest available owner-published source for the claim.
   • Use secondary sources only as pointers to primary sources. Do not cite them as authority.
   • If a needed source cannot be accessed, record the access gap. If no primary source can be accessed at all, stop and ask the user for source material or permission to write a gap-only artifact.

4. Investigate with claim-to-source traceability

   • Read enough source material to answer the question; do not stop at the first plausible result.
   • Attach every substantive claim to a source URL or repository path, with line numbers or anchors when available.
   • When sources disagree, record the conflict and identify which source is more authoritative instead of silently choosing.
   • Mark unsupported claims as UNVERIFIED or omit them.

5. Write the cited Markdown artifact

   • Use this structure:

   # Research: <question>
   
   ## Question
   
   <bounded question being answered>
   
   ## Scope
   
   - Included: <what was researched>
   - Excluded: <adjacent areas intentionally not researched>
   
   ## Sources
   
   - <source title or path> — <URL/path and why this is primary>
   
   ## Findings
   
   1. <source-backed finding with citation>
   2. <source-backed finding with citation>
   
   ## Conflicts And Gaps
   
   - <conflicting source, inaccessible source, or UNVERIFIED item>
   
   ## Non-Decisions
   
   - <decisions this research does not make>
   

   • Include the current date in the artifact only as artifact metadata, not in the skill instructions.
   • Do not include secrets, credentials, private customer data, raw production data, or sensitive logs. Summarize and redact when sensitive evidence is relevant.

6. Report completion

   • Return the artifact path, whether it was created, refreshed, overwritten, or written to a suffixed path, the number of primary sources used, and any conflicts or gaps that affect downstream planning.
   • If no artifact was written because source access failed, report the missing source access and the smallest source material needed to continue.

Artifact Lifecycle

• Produced by: Step 5 writes exactly one Markdown research artifact.
• Consumed by: Planning, discovery, implementation, review, or user decision workflows that need source-backed facts.
• Refreshed by: Re-run this skill when the question changes, dependency versions change, source documents move, or downstream work needs current facts, then explicitly choose update/overwrite when an existing artifact is found.
• Retired by: Delete or archive the artifact when the related planning or implementation work is complete, or when a newer research artifact supersedes it.

Error Handling

| Condition | Response | | --- | --- | | Missing question | Ask for one bounded research question. | | Output path cannot be written | Stop with the exact path and filesystem issue. | | Output path resolves outside the working tree | Warn with the exact resolved path and write only after explicit confirmation. | | Output path already exists | Ask whether to overwrite, refresh, choose a suffixed path, or abort. | | No primary source access | Ask for source material or permission to write a gap-only artifact. | | Only secondary sources found | Use them only to locate primary sources; otherwise record the gap. | | User asks for a decision | Provide source-backed facts and explicit non-decisions; route decision-making to the relevant planning workflow. |