Sokrates

---
name: sokrates
description: Start here for anything about Sokrates (sokrates.dev), the source-code analysis tool: analyze a repository, understand a codebase, set up or improve the Sokrates config, scan for risks, build a landscape of many repositories, improve code where it matters. Finds out where the user is and routes to the right sokrates-skill, running Sokrates when that is the next step.
---

# Sokrates (start here)

Sokrates measures a codebase - size, complexity, duplication, churn, coupling, contributors - and writes
one analysis per repository (`_sokrates/`) or one landscape over many (`_sokrates_landscape/`). The
other sokrates-skills configure it, add AI findings on top of its data, and act on what it found.
This skill decides which of them applies now. Do not guess the situation: measure it.

## 1. Find out where you are

```bash
python3 <this-skill-path>/scripts/situation.py [folder] [--json <scratch>/situation.json]
```

It prints the situation (repository or landscape, analysis present and how old, configuration tuned or
not, AI findings, how Sokrates can be run on this machine) and **ranked next steps, each naming the
skill or command**. Trust the order: a step only makes sense once the ones before it are done - findings
built on an untuned configuration describe the wrong scope, an improvement measured on a stale analysis
proves nothing.

## 2. Act on the first applicable step

| the script says | do |
| --- | --- |
| `[install]` | Sokrates is not on this machine. Tell the user the options (Docker image `ghcr.io/zeljkoobrenovic/sokrates`, the CLI jar) and stop; do not substitute your own analysis. |
| `[analyze]` | Run the printed command in the repository root (it includes git history extraction, `init` when there is no configuration, and the reports). Then re-run `situation.py`. |
| `[sokrates-repo-config]` `[sokrates-decompositions]` `[sokrates-features-of-interest]` `[sokrates-people-config]` | Load that skill and follow it. Every change to `config.json` is followed by `sokrates analyze` (or `generateReports`), so the data the next steps read is current. |
| `[full-scan]` | Load `full-scan`; it chooses the bundle (basic, a deep-dive family, or full) from what the user asked. A named worry ("is it secure", "well tested") goes straight to that scanner family. |
| `[sokrates-scan-core]` | Findings without an explorer page: run the printed `render_findings.py`. |
| `[sokrates-improve]` | Load `sokrates-improve`; it selects a target from the data, changes the code on a branch and proves the effect by re-measuring. |
| `[analyzeLandscape]` `[sokrates-landscape-config]` `[sokrates-virtual-landscapes]` | Landscape work: run the printed command, then the landscape skills. |

When the user named what they want, start from that and use the situation only to check the
prerequisites - "scan this repo" with no analysis means: analyze first, say so, then scan.

## 3. Running Sokrates

`situation.py` prints the form that works here, in this preference: `sokrates` on the PATH, the jar from
`SOKRATES_JAR`, or Docker (`docker run --rm -v "$(pwd):/code" ghcr.io/zeljkoobrenovic/sokrates <command>`).
The commands that matter:

| command | does |
| --- | --- |
| `analyze` | one repository, in place: git history, configuration if missing, reports under `_sokrates/` |
| `analyzeGitRepo -url <git url>` | clone, analyze, keep only the analysis under `<owner>/<repo>/` |
| `analyzeLandscape [-urls repos.txt]` | analyze every listed repository, then the landscape over all analyses under the root |
| `analyzeGitHubOrg -org <login>` / `analyzeGitLabGroup -group <path>` | a whole organization, one landscape per org |
| `-dataOnly` | only the `data.zip` - enough for every skill, much faster, no HTML |
| `-ai claude\|codex\|gemini` | run the agent with the skills after each analysis (incremental, `-aiMaxRepos`, `-aiForce`) |

Builds differ: older ones lack `-dataOnly`, `-ai`, `-prune`, the organization commands, or match scope
patterns against the whole path. Do not guess from dates — probe:

```bash
python3 <this-skill-path>/scripts/capabilities.py [--data _sokrates/reports/data/data.zip] [--json <scratch>/capabilities.json]
```

It runs the detected CLI, parses its usage into commands and options, says which capabilities the
installed build has and lacks (and which jar a `sokrates` wrapper runs), and with `--data` which exports
an analysis holds (history zip, units, duplicates, temporal dependencies, …). When a capability is
missing, say so and use the older form (`extractGitHistory` + `init` + `generateReports` instead of
`analyze`, a full run instead of `-dataOnly`) rather than failing on an unknown flag.

## 4. Which skill when (the map)

| you want | skill |
| --- | --- |
| the configuration right: scope, file classes, thresholds | `sokrates-repo-config` |
| meaningful components | `sokrates-decompositions` |
| debt markers, security-sensitive code, integrations, feature flags tracked | `sokrates-features-of-interest` |
| one person = one contributor | `sokrates-people-config` |
| what this codebase is, does, how it is built | `full-scan` (basic) |
| how good it is at testing, reliability, maintainability, risk | `full-scan` family `quality` |
| performance, storage, network, observability | `full-scan` family `runtime` |
| security, infrastructure, configuration | `full-scan` family `security` |
| the findings format, validation, explorer, merge, diff, re-check, summary | `sokrates-scan-core` |
| make the code better where the numbers say so, and prove it | `sokrates-improve` |
| a landscape: what gets aggregated, tags, teams | `sokrates-landscape-config` |
| sub-landscapes by naming, technology, team, activity | `sokrates-virtual-landscapes` |
| the portfolio story over a scanned landscape: concentration, recurring findings, coverage, priorities | `landscape-synthesis-scan` |

A named worry goes straight to its scanner (each writes validated findings; `full-scan` runs bundles of them):

| the question | scanner |
| --- | --- |
| what does this software do, for whom, through which entry points | `functionality-scan` |
| what do the domain concepts mean, where does the language drift | `domain-language-scan` |
| how is it structured, what depends on what, is the architecture eroding | `architecture-scan` |
| how did it get here, what is the trajectory | `evolution-scan` |
| which languages, frameworks, libraries, build and infra tooling | `tech-stack-scan` |
| how is it built, tested, released, deployed | `cicd-scan` |
| what runtime environment does it declare: Terraform, Kubernetes, Dockerfiles | `iac-scan` |
| how is it configured, where do settings and secrets come from | `configuration-scan` |
| how well is it tested, what is untested | `testing-scan` |
| what does it log, measure, trace; what stays dark | `observability-scan` |
| what happens when things fail: errors, retries, isolation | `reliability-scan` |
| where will it be slow, what scales badly | `performance-scan` |
| where does the data live, how is it versioned and kept intact | `storage-scan` |
| what does it connect to and listen on, what happens offline | `network-scan` |
| is it secure: identity, secrets, injection, crypto, trust | `security-scan` |
| how maintainable, graded per sub-characteristic and component | `maintainability-scan` |
| which files are risky and why, bus factor, change coupling | `risk-synthesis-scan` |

## 5. Rules shared by every skill

- Numbers come from the Sokrates data (`_sokrates/reports/data/data.zip`), never from reading the tree
  and estimating. Findings cite file, line and verbatim snippet and are validated before they are reported.
- Reports are generated artefacts: edit `config.json`, never a file under `reports/`.
- Say what was done and what was skipped. A scan that did not validate, an improvement that did not
  move the numbers, an analysis that could not run: report it as such.