Skill Researcher

Skill Researcher

When to Use

• User asks to "answer RQ-N", "fill in RQ-4", or "do the research for the agnosticd_user_info section"
• User says "update the skills with what you found" after a research fetch
• User wants to see which research questions are still open across the skill catalog
• User wants findings saved permanently so they are not repeated in future sessions

Do NOT use this skill to deploy or audit infrastructure — it operates on skill files, not on user environments.

Instructions

This skill defines a three-phase process. Work through the phases in order. Do not write any changes until Phase 1 is confirmed by the user.

Gotchas

• Always verify upstream documentation is current before writing findings — stale docs produce incorrect research results
• Research findings must be written into the AFFECTED skill's files, not into skill-researcher's own files
• Update the references/REFERENCE.md index in the target skill after adding any new reference file
• A single RQ may affect multiple skills — propagate findings to ALL affected skills, not just the one where the RQ was found
• Do not mark an RQ as resolved unless the finding includes a concrete code/config example, not just a prose description

Required Input

Before starting, collect:

Phase 1 — Discover

Scan all skills/*/SKILL.md files for lines matching (RESEARCH NEEDED — RQ-N) where N matches the target RQ. If the target is all, find every open block regardless of RQ number.

For each match, record:

• File path
• Section heading the block appears under
• The full RQ description (the line immediately after the (RESEARCH NEEDED — RQ-N) marker)

Report the complete list of write targets to the user before doing anything else:

Discovered write targets for RQ-4:
  skills/agnosticd/SKILL.md               → "Reporting Deployment Info"
  skills/agnosticd-refactor/SKILL.md      → "Audit Area 4: agnosticd_user_info Completeness"
  skills/showroom/SKILL.md                → "AgnosticD Data Integration"
  skills/student-readiness/SKILL.md       → "Check #7: Content-Environment Match"

Proceed with research? (y/n)

Wait for confirmation before proceeding to Phase 2.

Phase 2 — Research

2a. Find the upstream source

Read references/REFERENCE.md in the primary skill for this RQ (usually the refactor skill — agnosticd-refactor for AgnosticD RQs, vp-refactor for Validated Patterns RQs). Identify the most relevant upstream URL for the research question.

If no relevant URL is listed and the user did not provide one, stop and ask:

"No upstream source found in references/ for this RQ. Please provide the upstream URL to fetch, or confirm which existing reference document to consult."

2b. Fetch and extract

Fetch the upstream source. Extract only verified, exact content:

• Exact variable names (not approximations like "something like user_count")
• Exact module signatures, required parameters, and return values
• Exact file names and their required contents
• Exact playbook names and the Ansible tasks they must contain

Do not paraphrase or approximate. If the upstream source uses a specific term, use that term exactly.

2c. Compare against the user's project

Using the upstream guidance extracted in 2b as the requirements baseline, inspect the user's current project files (provided as the "Current project path or URL" input). For each requirement, determine:

• Matches — the project already implements this correctly
• Gaps — the project is missing this requirement or implements it incorrectly
• Unclear — the project has a file or variable that may be related but cannot be confirmed without more context

Record this comparison separately from the general finding. The skill file receives the general guidance (what upstream requires); the user receives the project-specific diagnosis (how their project measures up and what to fix).

2d. Verify sufficiency

Before proceeding to Phase 3, confirm that the extracted content is sufficient to replace every write target found in Phase 1. If any target requires information that was not found:

Research incomplete for RQ-N:
  Found: [what was found]
  Missing: [what is still needed — be specific]
  Suggested next source: [URL or repo path to check]

Stop and report. Do not write partial findings into the skill files — partial replacements are harder to identify as incomplete than explicit (RESEARCH NEEDED) blocks.

Phase 3 — Write Back

3a. Save the reference document

Before editing any SKILL.md file, save the research findings as a new Markdown file in the relevant skill's references/ directory:

• For AgnosticD RQs: skills/agnosticd/references/<topic>.md
• For Validated Patterns RQs: skills/vp-refactor/references/<topic>.md

The reference document should contain the raw extracted content — module signatures, variable tables, code examples — with a link to the upstream source at the top.

Then update the references/REFERENCE.md index in that directory to list the new file.

3b. Replace the placeholder blocks

For each write target confirmed in Phase 1, replace the entire (RESEARCH NEEDED — RQ-N) block — from the opening > blockquote line to the closing blank line — with the verified content.

Use consistent formatting across all files:

• Use a Markdown table for variable/parameter lists
• Use fenced code blocks with language tags for code examples
• Keep the section heading unchanged
• Remove the (RESEARCH NEEDED) marker and the "Current partial guidance:" label — replace both with the full verified content

3c. Report the write-back

Present a summary table when all writes are complete:

Research Write-Back — RQ-N: <topic>
──────────────────────────────────────────────────────
 File                              Section            Status
 agnosticd/SKILL.md               <section>          UPDATED
 agnosticd-refactor/SKILL.md      <section>          UPDATED
 showroom/SKILL.md                <section>          UPDATED
 student-readiness/SKILL.md       <section>          UPDATED
──────────────────────────────────────────────────────
 Reference saved: skills/agnosticd/references/<topic>.md
 REFERENCE.md updated: skills/agnosticd/references/REFERENCE.md

Phase 4 — Upstream Contribution (Optional)

This phase is optional. Activate it after Phase 3 write-back is complete when research reveals a gap, missing documentation, or undocumented behavior in the upstream project itself.

When to Activate Phase 4

Activate Phase 4 when: the user's project correctly implements what the upstream guidance specifies, and the upstream tool still does not behave as documented. This is the key distinction:

• Missing or unclear upstream documentation → update the skill files locally (Phase 3). Do not open an upstream issue just because documentation is sparse.
• Project correctly follows the guidance; tool doesn't behave as documented → this is an upstream bug or documentation inaccuracy worth reporting. Activate Phase 4.

If the project has gaps (found in Phase 2c), address those gaps with the user first. Phase 4 is only warranted when the project is correct and the tool is wrong.

If none of these conditions apply, skip Phase 4.

Upstream Issue Tracker Lookup

Use this table to identify the correct upstream repository for an issue or PR:

Phase 4a — Draft the Contribution

Offer the user a choice before doing anything:

The user's project correctly implements the upstream guidance, but the tool does not behave as documented:
  [describe the specific discrepancy — what the docs say vs. what the tool does]

Would you like to:
  (A) Create a GitHub issue to report the discrepancy
  (B) Create a GitHub PR with a documentation or code fix (doc-only changes unless user is a contributor)
  (C) Skip — keep the finding in the skill file only

Wait for the user's choice before drafting anything.

For GitHub Issues (option A):

Draft the issue for user review before any gh command is run:

Proposed issue for: <upstream repo>

Title: [Concise description of the missing documentation]

Body:
## Summary
[One paragraph describing what is missing]

## Expected documentation
[What should be documented and where]

## Why this matters
[Impact on users — what goes wrong without this doc]

## Suggested content
[Draft of the missing documentation or schema]

Approve this draft? (y/n)

For GitHub PRs (option B — doc-only changes only):

Only offer this path if:

• The fix is documentation only (Markdown, YAML schema docs, README updates)
• The user has a fork of the upstream repository or is willing to create one

Draft the corrected content for user review first. Never run gh pr create without explicit user approval of both the content and the target branch.

Phase 4b — Create the Contribution

Only after the user approves the draft:

# GitHub Issue
gh issue create \
  --repo <owner>/<repo> \
  --title "<approved title>" \
  --body "<approved body>"

# GitHub PR (user must have fork set up)
gh pr create \
  --repo <owner>/<repo> \
  --title "<approved title>" \
  --body "<approved body>" \
  --base main

Phase 4 Output

Report the result:

Phase 4 — Upstream Contribution
──────────────────────────────────────
 Type:       GitHub Issue
 Repo:       validatedpatterns/validatedpatterns.io
 Title:      Document pattern-metadata.yaml required fields
 URL:        https://github.com/validatedpatterns/validatedpatterns.io/issues/NNN
──────────────────────────────────────
 The issue has been filed. The (SCHEMA PENDING) marker in
 skills/vp-refactor/references/pattern-metadata.md will be
 resolved once the upstream docs are updated and re-fetched.

Read references/rq-registry.md when discovering which RQs exist or checking their status.

Escalation

• Upstream source has changed significantly from what the skill describes → flag for a full skill review via the agnosticd-refactor or vp-refactor skill, not just a placeholder fill
• RQ spans both AgnosticD and Validated Patterns → run two separate research sessions, one per ecosystem, using the appropriate refactor skill as the primary reference
• Upstream source requires authentication or is behind a VPN → stop and ask the user to provide the content directly as a paste, then proceed with Phase 3 using the pasted content as the source