Skip to content

ericrisco/rsc-harness / skills/codebase-onboarding

codebase-onboarding

Verified

Use when you land in an unfamiliar or inherited codebase and must get productive fast: a breadth-first map of entry points, request flow, module ownership, hidden side effects (cron, webhooks, workers) and churn hotspots, committed as CODEBASE-MAP.md. NOT a deep audit of one module (that is `analyze`) or chasing one failure (that is `debug`).

FileKindSize
SKILL.mdskill md9.3 KB
evals/README.mdmarkdown1.0 KB
evals/cases.yamlconfig4.4 KB
references/recon-playbook.mdmarkdown4.4 KB
scripts/verify.shexecutablescript1.8 KB

scripts/verify.sh

View on GitHub
#!/usr/bin/env bash
# verify.sh — structural check for the codebase-onboarding artifact.
#
# Validates that a CODEBASE-MAP.md contains the required sections. This is a
# STRUCTURE check, not a content-correctness check (this is a process skill;
# its real rigor is the capability eval). Read-only: it never writes or edits.
#
# Usage:   verify.sh [path-to-map]      (default: ./CODEBASE-MAP.md)
# Exit 0:  map present with all required sections, OR no map yet (nothing to
#          check — an empty/clean target must not produce a false failure).
# Exit 1:  map present but missing one or more required sections.

set -euo pipefail

MAP="${1:-CODEBASE-MAP.md}"

# No artifact yet => nothing to validate. Clean target, exit 0 (no false fail).
if [[ ! -f "$MAP" ]]; then
  echo "OK: no $MAP yet — nothing to verify (run the recon pass to produce one)."
  exit 0
fi

# Required section headers. Each entry is an extended-regex alternation so that
# reasonable wording variants (e.g. "Request flow" / "Data flow") still pass.
declare -a SECTIONS=(
  "Stack"
  "Entry points?"
  "Request flow|Data flow"
  "Module ownership"
  "Hidden behavior|Hidden behaviour|Side effects?"
  "Hotspots?"
  "How to run|Running locally"
)

missing=()
for pat in "${SECTIONS[@]}"; do
  # Match a markdown heading line (## ...) containing the pattern, case-insensitive.
  if ! grep -Eiq "^#{1,6}[[:space:]].*(${pat})" "$MAP"; then
    # Use the first alternative as the human-readable label.
    missing+=("${pat%%|*}")
  fi
done

if (( ${#missing[@]} > 0 )); then
  echo "FAIL: $MAP is missing required section(s):" >&2
  for m in "${missing[@]}"; do
    echo "  - $m" >&2
  done
  echo "Required: Stack, Entry points, Request flow, Module ownership, Hidden behavior, Hotspots, How to run." >&2
  exit 1
fi

echo "OK: $MAP has all required sections."
exit 0
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall