# Inputs for <skill-name>

This file is the contract for what the skill consumes. The using-agent reads it
and, for every **NEEDED** input that is missing, **asks the user** before doing
anything else — quoting the path, how to retrieve it, and the alternatives.
Never invent a NEEDED input.

## NEEDED  (the skill cannot proceed without these)

- **<input_key>**: <what it is, in one line>
  - where: `<expected path, e.g. examples/<bench>/tasks.jsonl>`
  - how to get it: `<command or steps to produce it>`
  - options: `<alternative forms — a file | a directory | a callable in adapters/>`

## RECOMMENDED  (improve results; degrade gracefully if absent)

- **<input_key>**: <what it is>
  - where: `<path>`
  - how to get it: `<command>`
  - default if absent: `<the fallback behavior + a note that it was skipped>`

## Notes
- Paths are relative to the repo root unless absolute.
- Anything the agent fills here should be written back so the run is reproducible.

# Prompt template — <skill-name>

> This is the prompt handed to the model when this skill drives an LLM step.
> Replace `{{placeholders}}` with values resolved from `inputs/INPUTS.md`.
> If a skill performs no LLM step (pure mechanical run), this file documents the
> reasoning the agent should follow instead.

## Role
You are <the role this step plays, e.g. "the evaluator" / "the diagnoser" / "the optimizer">.

## Context
{{context}}

## Task
{{task_instructions}}

## Constraints
- Honest evaluation is sacred: never peek at or score the test split here.
- {{additional_constraints}}

## Output
{{output_contract}}   # e.g. "Print a single JSON object: {...}"

# Concepts — <skill-name>

> Grounded background and the *why* behind this skill's design. Cite sources in
> the `sources:` frontmatter and reference them here. Keep claims reliable —
> prefer primary sources (papers, the actual optimizer's docs/code) over guesses.

## The idea
<What problem this step solves and the mental model to hold.>

## How it fits the pipeline
<What it consumes (`needs`) and produces (`provides`), and which skills sit on
either side of it.>

## Why it's built this way
<Design rationale, tradeoffs, and the honest-eval implications.>

## Sources
- <citation 1>
- <citation 2>

# Examples — <skill-name>

> Concrete, runnable worked examples. Show the command, representative inputs,
> and the exact JSON the skill prints. Examples teach the agent the shape of the
> work far faster than prose.

## Example 1 — <short title>
```
<command>
```
Input: `<...>`

Output:
```json
{ "...": "..." }
```
Notes: <what to notice>.

# Pitfalls & important points — <skill-name>

> Related problems, failure modes, and the things that go wrong in practice.
> This is where hard-won, cited knowledge lives.

## Failure modes
- **<failure>**: <how it shows up> → <how to avoid/detect it>.

## Easy to get wrong
- <subtle point>.

## Honesty guardrails
- Never score or peek at the test split outside `finalize`.
- Gate acceptance on val, never on the data the optimizer edited against.

"""Abstract methods for <skill-name> — IMPLEMENT THESE.

The optimizer agent implements every method below. Each stub raises
NotImplementedError with the "IMPLEMENT ME" marker so `check.py` can detect and
report exactly what is unfilled. Replace the body, keep the signature.

Many skills delegate to the project-level adapter in
``.capevolve/project/adapters/adapter.py`` (the CapabilityAdapter: 3 required methods
plus defaulted hooks). If this skill's work is fully covered there, import and call it
rather than duplicating.
"""

from __future__ import annotations

IMPLEMENT_MARKER = "IMPLEMENT ME"


def example_abstract_method(*args, **kwargs):
    """Replace with the real method(s) this skill needs.

    Document inputs/outputs precisely; downstream skills depend on the shape.
    """
    raise NotImplementedError(f"{IMPLEMENT_MARKER}: example_abstract_method")

"""Per-skill gate for <skill-name>.

Every check must prove a BEHAVIORAL contract (not just that run.py imports) via
the shared ``cap_evolve.skillcheck`` harness. The import-smoke base
(``require_main``) is kept, but add at least one real assertion about what this
skill guarantees. Exit 0 only when green; the orchestration prompt requires every
involved skill's check to be green before spending optimization budget.
"""

from __future__ import annotations

import sys

import _bootstrap  # noqa: F401  (locates cap_evolve)

from cap_evolve.skillcheck import Checker, import_run


def main() -> int:
    c = Checker("<skill-name>")
    run = import_run()
    c.require_main(run)

    # TODO per skill: assert the real contract, e.g. feed a synthetic input and
    # check the output shape, or assert an honesty invariant the skill enforces.
    # c.check(<condition>, "<what went wrong>", note="<what this proves>")

    return c.emit()


if __name__ == "__main__":
    sys.exit(main())

"""Pipeline/run script for <skill-name>.

Assumes `check.py` is green. Wires the implemented abstract methods into
`cap_evolve`, performs this skill's step, and prints a single JSON object to
stdout (the contract surface consumed by downstream skills / non-Python hosts).
"""

from __future__ import annotations

import argparse
import json
import sys

import _bootstrap  # noqa: F401

import abstract  # noqa: F401  (the implemented methods)


def main(argv=None) -> int:
    p = argparse.ArgumentParser(prog="<skill-name> run")
    p.add_argument("--run-dir", default=None, help="path to the active .capevolve/run_* dir")
    # add skill-specific args here
    args = p.parse_args(argv)

    result = {
        "skill": "<skill-name>",
        # fill with this skill's output (shape documented in SKILL.md / meta.yaml provides)
    }
    print(json.dumps(result))
    return 0


if __name__ == "__main__":
    sys.exit(main())

"""Thin shim: locate cap_evolve, then defer to cap_evolve._bootstrap.

Skill scripts ``import _bootstrap`` first. The real path-resolution logic lives
ONCE in ``cap_evolve._bootstrap`` (so it can't drift across skills); this shim
only has to find that package, which means a minimal upward walk for ``core/`` —
the single bit of bootstrapping that genuinely must run before cap_evolve is
importable. Everything else delegates.
"""

from __future__ import annotations

import os
import sys
from pathlib import Path


def _seed_path() -> None:
    """Minimal: put a dir containing the cap_evolve package on sys.path."""
    try:
        import cap_evolve  # noqa: F401
        return
    except Exception:
        pass
    cands = []
    env = os.environ.get("CAPEVOLVE_CORE")
    if env:
        cands.append(Path(env))
    here = Path(__file__).resolve()
    for parent in here.parents:
        cands.append(parent / "core")
        cands.append(parent)
    for c in cands:
        if (c / "cap_evolve" / "__init__.py").exists():
            p = str(c)
            if p not in sys.path:
                sys.path.insert(0, p)
            return


_seed_path()
from cap_evolve._bootstrap import ensure_core  # noqa: E402

# Anchor the upward walk at THIS skill script's location (not the core module's).
ensure_core(Path(__file__).resolve())