@heytherevibin/skillforge 0.2.1

package/skills/santa-method/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: santa-method
+description: "Multi-agent adversarial verification with convergence loop. Two independent review agents must both pass before output ships."
+origin: "Ronald Skelton - Founder, RapportScore.ai"
+---
+
+# Santa Method
+
+Multi-agent adversarial verification framework. Make a list, check it twice. If it's naughty, fix it until it's nice.
+
+The core insight: a single agent reviewing its own output shares the same biases, knowledge gaps, and systematic errors that produced the output. Two independent reviewers with no shared context break this failure mode.
+
+## When to Activate
+
+Invoke this skill when:
+- Output will be published, deployed, or consumed by end users
+- Compliance, regulatory, or brand constraints must be enforced
+- Code ships to production without human review
+- Content accuracy matters (technical docs, educational material, customer-facing copy)
+- Batch generation at scale where spot-checking misses systemic patterns
+- Hallucination risk is elevated (claims, statistics, API references, legal language)
+
+Do NOT use for internal drafts, exploratory research, or tasks with deterministic verification (use build/test/lint pipelines for those).
+
+## Architecture
+
+```
+┌─────────────┐
+│  GENERATOR   │  Phase 1: Make a List
+│  (Agent A)   │  Produce the deliverable
+└──────┬───────┘
+       │ output
+       ▼
+┌──────────────────────────────┐
+│     DUAL INDEPENDENT REVIEW   │  Phase 2: Check It Twice
+│                                │
+│  ┌───────────┐ ┌───────────┐  │  Two agents, same rubric,
+│  │ Reviewer B │ │ Reviewer C │  │  no shared context
+│  └─────┬─────┘ └─────┬─────┘  │
+│        │              │        │
+└────────┼──────────────┼────────┘
+         │              │
+         ▼              ▼
+┌──────────────────────────────┐
+│        VERDICT GATE           │  Phase 3: Naughty or Nice
+│                                │
+│  B passes AND C passes → NICE  │  Both must pass.
+│  Otherwise → NAUGHTY           │  No exceptions.
+└──────┬──────────────┬─────────┘
+       │              │
+    NICE           NAUGHTY
+       │              │
+       ▼              ▼
+   [ SHIP ]    ┌─────────────┐
+               │  FIX CYCLE   │  Phase 4: Fix Until Nice
+               │              │
+               │ iteration++  │  Collect all flags.
+               │ if i > MAX:  │  Fix all issues.
+               │   escalate   │  Re-run both reviewers.
+               │ else:        │  Loop until convergence.
+               │   goto Ph.2  │
+               └──────────────┘
+```
+
+## Phase Details
+
+### Phase 1: Make a List (Generate)
+
+Execute the primary task. No changes to your normal generation workflow. Santa Method is a post-generation verification layer, not a generation strategy.
+
+```python
+# The generator runs as normal
+output = generate(task_spec)
+```
+
+### Phase 2: Check It Twice (Independent Dual Review)
+
+Spawn two review agents in parallel. Critical invariants:
+
+1. **Context isolation** — neither reviewer sees the other's assessment
+2. **Identical rubric** — both receive the same evaluation criteria
+3. **Same inputs** — both receive the original spec AND the generated output
+4. **Structured output** — each returns a typed verdict, not prose
+
+```python
+REVIEWER_PROMPT = """
+You are an independent quality reviewer. You have NOT seen any other review of this output.
+
+## Task Specification
+{task_spec}
+
+## Output Under Review
+{output}
+
+## Evaluation Rubric
+{rubric}
+
+## Instructions
+Evaluate the output against EACH rubric criterion. For each:
+- PASS: criterion fully met, no issues
+- FAIL: specific issue found (cite the exact problem)
+
+Return your assessment as structured JSON:
+{
+  "verdict": "PASS" | "FAIL",
+  "checks": [
+    {"criterion": "...", "result": "PASS|FAIL", "detail": "..."}
+  ],
+  "critical_issues": ["..."],   // blockers that must be fixed
+  "suggestions": ["..."]         // non-blocking improvements
+}
+
+Be rigorous. Your job is to find problems, not to approve.
+"""
+```
+
+```python
+# Spawn reviewers in parallel (Claude Code subagents)
+review_b = Agent(prompt=REVIEWER_PROMPT.format(...), description="Santa Reviewer B")
+review_c = Agent(prompt=REVIEWER_PROMPT.format(...), description="Santa Reviewer C")
+
+# Both run concurrently — neither sees the other
+```
+
+### Rubric Design
+
+The rubric is the most important input. Vague rubrics produce vague reviews. Every criterion must have an objective pass/fail condition.
+
+| Criterion | Pass Condition | Failure Signal |
+|-----------|---------------|----------------|
+| Factual accuracy | All claims verifiable against source material or common knowledge | Invented statistics, wrong version numbers, nonexistent APIs |
+| Hallucination-free | No fabricated entities, quotes, URLs, or references | Links to pages that don't exist, attributed quotes with no source |
+| Completeness | Every requirement in the spec is addressed | Missing sections, skipped edge cases, incomplete coverage |
+| Compliance | Passes all project-specific constraints | Banned terms used, tone violations, regulatory non-compliance |
+| Internal consistency | No contradictions within the output | Section A says X, section B says not-X |
+| Technical correctness | Code compiles/runs, algorithms are sound | Syntax errors, logic bugs, wrong complexity claims |
+
+#### Domain-Specific Rubric Extensions
+
+**Content/Marketing:**
+- Brand voice adherence
+- SEO requirements met (keyword density, meta tags, structure)
+- No competitor trademark misuse
+- CTA present and correctly linked
+
+**Code:**
+- Type safety (no `any` leaks, proper null handling)
+- Error handling coverage
+- Security (no secrets in code, input validation, injection prevention)
+- Test coverage for new paths
+
+**Compliance-Sensitive (regulated, legal, financial):**
+- No outcome guarantees or unsubstantiated claims
+- Required disclaimers present
+- Approved terminology only
+- Jurisdiction-appropriate language
+
+### Phase 3: Naughty or Nice (Verdict Gate)
+
+```python
+def santa_verdict(review_b, review_c):
+    """Both reviewers must pass. No partial credit."""
+    if review_b.verdict == "PASS" and review_c.verdict == "PASS":
+        return "NICE"  # Ship it
+
+    # Merge flags from both reviewers, deduplicate
+    all_issues = dedupe(review_b.critical_issues + review_c.critical_issues)
+    all_suggestions = dedupe(review_b.suggestions + review_c.suggestions)
+
+    return "NAUGHTY", all_issues, all_suggestions
+```
+
+Why both must pass: if only one reviewer catches an issue, that issue is real. The other reviewer's blind spot is exactly the failure mode Santa Method exists to eliminate.
+
+### Phase 4: Fix Until Nice (Convergence Loop)
+
+```python
+MAX_ITERATIONS = 3
+
+for iteration in range(MAX_ITERATIONS):
+    verdict, issues, suggestions = santa_verdict(review_b, review_c)
+
+    if verdict == "NICE":
+        log_santa_result(output, iteration, "passed")
+        return ship(output)
+
+    # Fix all critical issues (suggestions are optional)
+    output = fix_agent.execute(
+        output=output,
+        issues=issues,
+        instruction="Fix ONLY the flagged issues. Do not refactor or add unrequested changes."
+    )
+
+    # Re-run BOTH reviewers on fixed output (fresh agents, no memory of previous round)
+    review_b = Agent(prompt=REVIEWER_PROMPT.format(output=output, ...))
+    review_c = Agent(prompt=REVIEWER_PROMPT.format(output=output, ...))
+
+# Exhausted iterations — escalate
+log_santa_result(output, MAX_ITERATIONS, "escalated")
+escalate_to_human(output, issues)
+```
+
+Critical: each review round uses **fresh agents**. Reviewers must not carry memory from previous rounds, as prior context creates anchoring bias.
+
+## Implementation Patterns
+
+### Pattern A: Claude Code Subagents (Recommended)
+
+Subagents provide true context isolation. Each reviewer is a separate process with no shared state.
+
+```bash
+# In a Claude Code session, use the Agent tool to spawn reviewers
+# Both agents run in parallel for speed
+```
+
+```python
+# Pseudocode for Agent tool invocation
+reviewer_b = Agent(
+    description="Santa Review B",
+    prompt=f"Review this output for quality...\n\nRUBRIC:\n{rubric}\n\nOUTPUT:\n{output}"
+)
+reviewer_c = Agent(
+    description="Santa Review C",
+    prompt=f"Review this output for quality...\n\nRUBRIC:\n{rubric}\n\nOUTPUT:\n{output}"
+)
+```
+
+### Pattern B: Sequential Inline (Fallback)
+
+When subagents aren't available, simulate isolation with explicit context resets:
+
+1. Generate output
+2. New context: "You are Reviewer 1. Evaluate ONLY against this rubric. Find problems."
+3. Record findings verbatim
+4. Clear context completely
+5. New context: "You are Reviewer 2. Evaluate ONLY against this rubric. Find problems."
+6. Compare both reviews, fix, repeat
+
+The subagent pattern is strictly superior — inline simulation risks context bleed between reviewers.
+
+### Pattern C: Batch Sampling
+
+For large batches (100+ items), full Santa on every item is cost-prohibitive. Use stratified sampling:
+
+1. Run Santa on a random sample (10-15% of batch, minimum 5 items)
+2. Categorize failures by type (hallucination, compliance, completeness, etc.)
+3. If systematic patterns emerge, apply targeted fixes to the entire batch
+4. Re-sample and re-verify the fixed batch
+5. Continue until a clean sample passes
+
+```python
+import random
+
+def santa_batch(items, rubric, sample_rate=0.15):
+    sample = random.sample(items, max(5, int(len(items) * sample_rate)))
+
+    for item in sample:
+        result = santa_full(item, rubric)
+        if result.verdict == "NAUGHTY":
+            pattern = classify_failure(result.issues)
+            items = batch_fix(items, pattern)  # Fix all items matching pattern
+            return santa_batch(items, rubric)   # Re-sample
+
+    return items  # Clean sample → ship batch
+```
+
+## Failure Modes and Mitigations
+
+| Failure Mode | Symptom | Mitigation |
+|-------------|---------|------------|
+| Infinite loop | Reviewers keep finding new issues after fixes | Max iteration cap (3). Escalate. |
+| Rubber stamping | Both reviewers pass everything | Adversarial prompt: "Your job is to find problems, not approve." |
+| Subjective drift | Reviewers flag style preferences, not errors | Tight rubric with objective pass/fail criteria only |
+| Fix regression | Fixing issue A introduces issue B | Fresh reviewers each round catch regressions |
+| Reviewer agreement bias | Both reviewers miss the same thing | Mitigated by independence, not eliminated. For critical output, add a third reviewer or human spot-check. |
+| Cost explosion | Too many iterations on large outputs | Batch sampling pattern. Budget caps per verification cycle. |
+
+## Integration with Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| Verification Loop | Use for deterministic checks (build, lint, test). Santa for semantic checks (accuracy, hallucinations). Run verification-loop first, Santa second. |
+| Eval Harness | Santa Method results feed eval metrics. Track pass@k across Santa runs to measure generator quality over time. |
+| Continuous Learning v2 | Santa findings become instincts. Repeated failures on the same criterion → learned behavior to avoid the pattern. |
+| Strategic Compact | Run Santa BEFORE compacting. Don't lose review context mid-verification. |
+
+## Metrics
+
+Track these to measure Santa Method effectiveness:
+
+- **First-pass rate**: % of outputs that pass Santa on round 1 (target: >70%)
+- **Mean iterations to convergence**: average rounds to NICE (target: <1.5)
+- **Issue taxonomy**: distribution of failure types (hallucination vs. completeness vs. compliance)
+- **Reviewer agreement**: % of issues flagged by both reviewers vs. only one (low agreement = rubric needs tightening)
+- **Escape rate**: issues found post-ship that Santa should have caught (target: 0)
+
+## Cost Analysis
+
+Santa Method costs approximately 2-3x the token cost of generation alone per verification cycle. For most high-stakes output, this is a bargain:
+
+```
+Cost of Santa = (generation tokens) + 2×(review tokens per round) × (avg rounds)
+Cost of NOT Santa = (reputation damage) + (correction effort) + (trust erosion)
+```
+
+For batch operations, the sampling pattern reduces cost to ~15-20% of full verification while catching >90% of systematic issues.

package/skills/scientific-db-pubmed-database/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: pubmed-database
+description: Direct PubMed and NCBI E-utilities search workflows for biomedical literature, MeSH queries, PMID lookup, citation retrieval, and API-backed literature monitoring.
+origin: community
+---
+
+# PubMed Database
+
+Use this skill when a task needs biomedical literature from PubMed rather than
+general web search.
+
+## When to Use
+
+- Searching MEDLINE or life-sciences literature.
+- Building PubMed queries with MeSH terms, field tags, dates, or article types.
+- Looking up PMIDs, abstracts, publication metadata, or related citations.
+- Running systematic-review search passes that need repeatable search strings.
+- Using NCBI E-utilities directly from Python, shell, or another HTTP client.
+
+## Query Construction
+
+Start with the research question, split it into concepts, then combine concepts
+with Boolean operators.
+
+```text
+concept_1 AND concept_2 AND filter
+synonym_a OR synonym_b
+NOT exclusion_term
+```
+
+Useful PubMed field tags:
+
+- `[ti]`: title
+- `[ab]`: abstract
+- `[tiab]`: title or abstract
+- `[au]`: author
+- `[ta]`: journal title abbreviation
+- `[mh]`: MeSH term
+- `[majr]`: major MeSH topic
+- `[pt]`: publication type
+- `[dp]`: date of publication
+- `[la]`: language
+
+Examples:
+
+```text
+diabetes mellitus[mh] AND treatment[tiab] AND systematic review[pt] AND 2023:2026[dp]
+(metformin[nm] OR insulin[nm]) AND diabetes mellitus, type 2[mh] AND randomized controlled trial[pt]
+smith ja[au] AND cancer[tiab] AND 2026[dp] AND english[la]
+```
+
+## MeSH and Subheadings
+
+Prefer MeSH when the concept has a stable controlled-vocabulary term. Combine
+MeSH with title/abstract terms when the topic is new or terminology varies.
+
+Correct subheading syntax puts the subheading before the field tag:
+
+```text
+diabetes mellitus, type 2/drug therapy[mh]
+cardiovascular diseases/prevention & control[mh]
+```
+
+Use `[majr]` only when the topic must be central to the paper. It can improve
+precision but may miss relevant work.
+
+## Filters
+
+Publication types:
+
+- `clinical trial[pt]`
+- `meta-analysis[pt]`
+- `randomized controlled trial[pt]`
+- `review[pt]`
+- `systematic review[pt]`
+- `guideline[pt]`
+
+Date filters:
+
+```text
+2026[dp]
+2020:2026[dp]
+2026/03/15[dp]
+```
+
+Availability filters:
+
+```text
+free full text[sb]
+hasabstract[text]
+```
+
+## E-utilities Workflow
+
+NCBI E-utilities supports repeatable API workflows:
+
+1. `esearch.fcgi`: search and return PMIDs.
+2. `esummary.fcgi`: return lightweight article metadata.
+3. `efetch.fcgi`: fetch abstracts or full records in XML, MEDLINE, or text.
+4. `elink.fcgi`: find related articles and linked resources.
+
+Use an email and API key for production scripts. Store API keys in environment
+variables, never in committed files or command history.
+
+```python
+import os
+import time
+import requests
+
+BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+
+
+def esearch(query: str, retmax: int = 20) -> list[str]:
+    params = {
+        "db": "pubmed",
+        "term": query,
+        "retmode": "json",
+        "retmax": retmax,
+        "tool": "pubmed-search",
+        "email": os.environ.get("NCBI_EMAIL", ""),
+    }
+    api_key = os.environ.get("NCBI_API_KEY")
+    if api_key:
+        params["api_key"] = api_key
+
+    response = requests.get(f"{BASE}/esearch.fcgi", params=params, timeout=30)
+    response.raise_for_status()
+    time.sleep(0.35)
+    return response.json()["esearchresult"]["idlist"]
+
+
+pmids = esearch("hypertension[mh] AND randomized controlled trial[pt] AND 2024:2026[dp]")
+print(pmids)
+```
+
+For batches, prefer NCBI history server parameters (`usehistory=y`,
+`WebEnv`, `query_key`) instead of passing very long PMID lists through URLs.
+
+## Output Discipline
+
+For each search pass, record:
+
+- exact search string
+- database searched
+- date searched
+- filters used
+- result count
+- export format
+- any manual exclusions
+
+Example:
+
+```markdown
+| Database | Date searched | Query | Filters | Results |
+| --- | --- | --- | --- | ---: |
+| PubMed | 2026-05-11 | `sickle cell disease[mh] AND CRISPR[tiab]` | 2020:2026[dp], English | 42 |
+```
+
+## Review Checklist
+
+- Are field tags valid PubMed tags?
+- Are MeSH terms paired with free-text synonyms for newer topics?
+- Is the date range explicit and appropriate?
+- Does the search log include enough detail to reproduce the query?
+- Are API keys loaded from the environment?
+- Does HTTP code call `raise_for_status()` or otherwise handle non-200
+  responses before parsing?
+- Are rate limits respected?
+
+## References
+
+- [PubMed help](https://pubmed.ncbi.nlm.nih.gov/help/)
+- [NCBI E-utilities documentation](https://www.ncbi.nlm.nih.gov/books/NBK25501/)
+- [NCBI API key guidance](https://support.nlm.nih.gov/kbArticle/?pn=KA-05317)
+- NCBI support: <eutilities@ncbi.nlm.nih.gov>

package/skills/scientific-db-uspto-database/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: uspto-database
+description: USPTO patent and trademark data workflow for official record lookup, PatentSearch queries, TSDR checks, assignment data, and reproducible IP research logs.
+origin: community
+---
+
+# USPTO Database
+
+Use this skill when a task needs official United States patent or trademark
+records from USPTO systems.
+
+## When to Use
+
+- Searching granted patents or pre-grant publications.
+- Checking patent application status, file-wrapper data, assignments, or
+  public prosecution history.
+- Looking up trademark status, documents, or assignment history.
+- Building reproducible prior-art, portfolio, or IP landscape research logs.
+- Comparing USPTO records with secondary tools such as Google Patents,
+  Lens.org, Semantic Scholar, or company patent pages.
+
+Do not use this skill to give legal advice. Treat it as a data-gathering and
+record-verification workflow.
+
+## Source Selection
+
+Prefer official USPTO or USPTO-supported surfaces first:
+
+- Open Data Portal (ODP): current home for migrated USPTO datasets and APIs.
+- Patent File Wrapper: public patent application bibliographic data and file
+  wrapper records.
+- PatentSearch API: PatentsView search API for granted patents and pre-grant
+  publication datasets.
+- TSDR Data API: trademark status and document retrieval.
+- Patent and Trademark Assignment Search: ownership transfer records.
+- PTAB data in ODP: Patent Trial and Appeal Board proceedings.
+
+Use secondary sources only as convenience indexes. When the answer matters,
+cross-check the official record.
+
+## Authentication and Secrets
+
+Many USPTO API flows require an API key. Store keys in environment variables or
+a secret manager, never in committed files or pasted transcripts.
+
+Common environment names:
+
+```bash
+export USPTO_API_KEY="..."
+export PATENTSVIEW_API_KEY="..."
+```
+
+For PatentSearch, send the key with the `X-Api-Key` header. For TSDR, follow
+the current USPTO API Manager instructions and rate-limit guidance.
+
+## PatentSearch Workflow
+
+Use PatentSearch for broad patent and pre-grant publication search when the
+question is about trends, inventors, assignees, classifications, dates, or
+portfolio slices.
+
+Workflow:
+
+1. Identify the endpoint from the current PatentSearch reference or Swagger UI.
+2. Build a JSON query with explicit filters.
+3. Request only the fields needed for the analysis.
+4. Sort and paginate deterministically.
+5. Record the endpoint, query body, date, data currency note, and result count.
+
+Python request skeleton:
+
+```python
+import os
+import requests
+
+API_KEY = os.environ["PATENTSVIEW_API_KEY"]
+BASE = "https://search.patentsview.org/api/v1"
+
+payload = {
+    "q": {
+        "_and": [
+            {"patent_date": {"_gte": "2024-01-01"}},
+            {"assignees.assignee_organization": {"_text_any": ["Google", "Alphabet"]}},
+        ]
+    },
+    "f": ["patent_id", "patent_title", "patent_date"],
+    "s": [{"patent_date": "desc"}],
+    "o": {"per_page": 100, "page": 1},
+}
+
+response = requests.post(
+    f"{BASE}/patent/",
+    headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"},
+    json=payload,
+    timeout=30,
+)
+response.raise_for_status()
+print(response.json())
+```
+
+Before reusing a query, verify current endpoint names, field paths, request
+parameters, and API-key availability in the live PatentSearch docs.
+
+## Trademark/TSDR Workflow
+
+Use TSDR when the task needs trademark case status, documents, images, owner
+history, or prosecution events.
+
+Workflow:
+
+1. Normalize the serial number or registration number.
+2. Check the current TSDR API instructions and required API-key header.
+3. Fetch status first, then documents only if needed.
+4. Respect the lower rate limit for PDF, ZIP, and multi-case downloads.
+5. Capture retrieval date and serial/registration identifier in the output.
+
+For large trademark pulls, prefer documented bulk-data flows rather than
+screen-scraping public pages.
+
+## File Wrapper and Prosecution History
+
+For application status, transaction history, and prosecution documents:
+
+- Start with ODP Patent File Wrapper search.
+- Use exact identifiers when available: application number, publication number,
+  patent number, or party name.
+- Record whether the record is a granted patent, pre-grant publication, or
+  pending application.
+- Cross-check document dates and status against the record detail page before
+  citing them.
+
+## Assignment Workflow
+
+For patent or trademark ownership:
+
+1. Search official assignment data by patent/application/registration number,
+   assignor, assignee, or reel/frame when available.
+2. Record conveyance text, execution date, recordation date, and parties.
+3. Distinguish assignment records from current legal ownership conclusions.
+4. If ownership is material, flag the result for attorney or subject-matter
+   review.
+
+## Reproducible Output
+
+Every USPTO research pass should include a log table:
+
+```markdown
+| Source | Date searched | Identifier/query | Filters | Results | Notes |
+| --- | --- | --- | --- | ---: | --- |
+| PatentSearch | 2026-05-11 | `assignee=Alphabet AND date>=2024` | patent endpoint | 118 | API docs checked before run |
+| TSDR | 2026-05-11 | `serial=90000000` | status only | 1 | API-key flow, no document bulk pull |
+```
+
+For final writeups, separate:
+
+- official record facts
+- inferred analysis
+- secondary-source convenience matches
+- unresolved gaps or records that require legal review
+
+## Review Checklist
+
+- Did you use an official USPTO or USPTO-supported source first?
+- Did you verify current endpoint and field names before running code?
+- Are API keys kept out of files, shell history, and output logs?
+- Does the query log include the date searched and exact request shape?
+- Are rate limits respected?
+- Are legal conclusions avoided or explicitly escalated?
+- Are secondary sources labeled as secondary?
+
+## References
+
+- [USPTO APIs catalog](https://developer.uspto.gov/api-catalog)
+- [USPTO Open Data Portal](https://data.uspto.gov/)
+- [PatentSearch API reference](https://search.patentsview.org/docs/docs/Search%20API/SearchAPIReference/)
+- [PatentSearch API updates](https://search.patentsview.org/docs/)
+- [TSDR API bulk download FAQ](https://developer.uspto.gov/faq/tsdr-api-bulk-download)