ra1-report

Files (66)

• SKILL.md
• manifest.json
• __init__.py · scripts/readiness/
• answers.py · scripts/readiness/
• __init__.py · scripts/readiness/checks/
• _agent_policy.py · scripts/readiness/checks/
• _helpers.py · scripts/readiness/checks/
• _workflow_policy.py · scripts/readiness/checks/
• build.py · scripts/readiness/checks/
• devenv.py · scripts/readiness/checks/
• docs.py · scripts/readiness/checks/
• judgment.py · scripts/readiness/checks/
• loop.py · scripts/readiness/checks/
• observability.py · scripts/readiness/checks/
• product.py · scripts/readiness/checks/
• security.py · scripts/readiness/checks/
• style.py · scripts/readiness/checks/
• taskdisc.py · scripts/readiness/checks/
• testing.py · scripts/readiness/checks/
• cli.py · scripts/readiness/
• __init__.py · scripts/readiness/collectors/
• _observation.py · scripts/readiness/collectors/
• exec.py · scripts/readiness/collectors/
• git.py · scripts/readiness/collectors/
• github.py · scripts/readiness/collectors/
• static.py · scripts/readiness/collectors/
• context.py · scripts/readiness/
• coverage_gate.py · scripts/readiness/
• registry.json · scripts/readiness/criteria/
• detect.py · scripts/readiness/
• __init__.py · scripts/readiness/fix/
• recipes.py · scripts/readiness/fix/
• gaps.py · scripts/readiness/
• history.py · scripts/readiness/
• judgments.py · scripts/readiness/
• model.py · scripts/readiness/
• parsers.py · scripts/readiness/
• process.py · scripts/readiness/
• report.py · scripts/readiness/
• run.py · scripts/readiness/
• safe_io.py · scripts/readiness/
• score.py · scripts/readiness/
• theme.py · scripts/readiness/
• version.py · scripts/readiness/
• AGENTS.md · templates/
• CODEOWNERS · templates/
• bug_report.md · templates/ISSUE_TEMPLATE/
• SECURITY.md · templates/
• guide-skill.md · templates/acdc/
• solve-skill.md · templates/acdc/
• verify-skill.md · templates/acdc/
• workflow.md · templates/acdc/
• readiness.yml · templates/ci/
• dependabot.yml · templates/
• devcontainer.json · templates/
• env.example · templates/
• eslintrc.json · templates/
• gitignore.ra1 · templates/
• denylist.md · templates/loop/
• loop-runs-README.md · templates/loop/
• …and 6 more

SKILL.md (first lines)

# Agent Readiness Report

Produce a trustworthy readiness report for a repository. The **deterministic engine owns the
score**; you (the agent) add **advisory** commentary only. You must never change the engine's score,
reason codes, evidence, or limitations, and you must never invent any of them.

## Steps

`<skill-dir>` below is this skill's own directory: the absolute path your runtime reports when it
loads the skill. Substitute it. Do not write `$(dirname "$0")` — in a shell tool call `$0` is the
shell, not this file.

1. **Run the engine** (it does all the deterministic work — file/config parsing, git history, and,
   when requested, the GitHub.com API). The repository must have `.ra1/reports/` ignored in its
   root `.gitignore` for in-repo persistence; otherwise the engine prints the full report in memory
   and reports the exact isolation error, which you present as storage unavailable while the
   assessment itself is complete.

   ```bash
   python3 -I "<skill-dir>/scripts/readiness/cli.py" report --project . \
     --format json,markdown,html --out .ra1/reports --store-history
   ```

   JSON is first so stdout is the canonical machine payload; Markdown/HTML/history are safe
   engine-written artifacts. T2 GitHub checks are offline by default; append the fixed `--github`
   only after an explicit current-turn request for GitHub/T2, and paired `--host-proxy` only after
   a separate current-turn host-proxy request. Never append `--exec`, `--exec-timeout`, `--require-origin`,
   shell composition, or a repository-derived option. A scan failure, truncation, or invalid JSON
   fails closed: never reconstruct a score from partial output.

2. **Check for unanswered questions.** If the engine's `gaps` array is non-empty, some `unknown`
   results are stuck on an input the scan could not infer, not on the repository. Report the count
   and the gating criteria they hold back, and hand off to the **ra1-interview** skill. Never answer
   them on the developer's behalf and never treat an unanswered gap as a finding.

3. **Copy the score verbatim.** Your final report MUST contain a fenced ```json block holding the
   engine's `score` object **exactly** — every key: `level`, `level_name`, `pass_rate`,
   `gating_passed`, `gating_total`, `levels`, `pillars`, `recommendations`, `max_available_level`,
   `next_gate_actions`, `evidence_coverage`. Full parsed-JSON deep equality; do not change a number.

4. **Add `## Evidence explanations`** (BEFORE `## T4 Advisory`). One fenced JSON object with this
   exact shape, covering every id in `score.next_gate_actions` in that order:

   ```json
   {
     "explanations": [
       {
         "id": "criterion.id",
         "status": "fail",
         "reason_code": "criterion.id.missing",
         "rule_ref": "checks.module.function",
         "evidence_sources": ["path-or-endpoint"],
         "limitations": ["deterministic limitation"]
       }
     ]
   }
   ```

   Values are copied from the matching result and its `decision_trace`; `evidence_sources` keeps
   first-seen non-empty sources, deduplicated. When `next_gate_actions` is empty, emit
   `{"explanations": []}`. Never author a new source, reason code, status, rule reference,
   limitation, or score. Then, in human prose, explain rule → observations → evaluation →
   limitation → next action in repository-maintainer language, citing criterion ids and sources,
   and label any T4 interpretation as advisory.

5. **Add `## T4 Advisory`** (qualitative, non-gating). The engine deliberately leaves these soft
   judgments to you; label each as advisory opinion grounded strictly in engine findings and files
   you actually read. Use one labelled sub-heading per registered judgment id (`naming_consistency`,
   `code_modularization`, `n_plus_one_query`, `readme_quality`, `agents_md_quality`,
   `service_flow_doc_quality`, `runbooks_quality`, `pii_handling`, `privacy_compliance`,
   `user_feedback_loop`), group AC/DC maturity by the registry-provided `acdc_stage`/`acdc_loop`
   fields, cite the specific file/finding, explain *why* it matters, and give the highest-leverage
   next step. Keep every T4 claim clearly separate from the deterministic score.

## Contract (do not violate)

- **Never claim a higher Level than the engine reports.** Level 5 (Autonomous) is reserved and
  never reported; the ceiling is stated as L4.
- **Never mark a failing or unknown criterion as passing.** Prose must agree with the engine's
  statuses; describe unavailable/unknown language honestly ("not verified", never "not protected").
- **Never invent criteria, evidence, sources, reason codes, or results** — pasting the score and
  explanation payloads verbatim is the machine contract; the human prose summarizes, never extends,
  them.
- **Never claim autonomy clearance** or unattended operation in any form.
- **Do not assert that a specific criterion is "gating" or "non-gating"** — only the engine's data
  says so.
- T4 advisory is opinion and is explicitly **non-gating** — it cannot move the Level, GitHub
  annotations, JUnit, or SARIF.

## Notes

- If the engine reports `project_type: unknown`, surface that honestly — type-dependent criteria are
  `unknown`, not silently skipped. Point at the `ra1-interview` skill to pin a type (never edit
  `.ra1/config.json` directly).
- T2 criteria are `skipped` when `--github` was not requested or the source is unavailable; say so
  and offer `--github` for a fuller scan.
- To raise the score, hand off to the **ra1-fix** skill (the Loadout).

From tjboudreaux/ready-agent-1, MIT.

More from tjboudreaux/ready-agent-1