Repository Readiness Evaluation
Systematic 4-axis assessment of whether a repository is ready for productive AI-assisted development — from code comprehension through successful test execution.
When to Use
- Onboarding to an unfamiliar repository
- Assessing if a codebase is AI-agent-ready
- Validating CI/CD pipeline health
- Pre-engagement quality check before committing to a project
- Measuring improvement after fixing build/test issues
The 4 Axes
| Axis |
Question |
Score Range |
| A: Code Understanding |
Can you comprehend the project structure, tech stack, and architecture? |
0–5 |
| B: Dependency Restore |
Can you install/restore all dependencies successfully? |
0–5 |
| C: Build Success |
Does the project compile/build without errors? |
0–5 |
| D: Test Execution |
Do tests run and pass? |
0–5 |
Total: 0–20 points → Tier classification (below)
Phase 1: Code Understanding (Axis A)
Investigation Steps
- Read README — does it explain setup, architecture, and conventions?
- Identify tech stack — languages, frameworks, build system, package manager
- Map project structure — entry points, module boundaries, config files
- Find build/run commands — documented or discoverable from manifests
- Identify test framework — what runs tests, where are they located
Scoring Rubric
| Score |
Criteria |
| 5 |
Clear docs, standard structure, obvious entry points, well-organized |
| 4 |
Minor gaps but navigable — missing some docs, non-standard naming |
| 3 |
Understandable with effort — sparse docs, complex structure |
| 2 |
Confusing — unclear entry points, mixed concerns, minimal docs |
| 1 |
Barely comprehensible — no docs, non-standard everything |
| 0 |
Cannot determine project purpose or structure |
Phase 2: Dependency Restore (Axis B)
Investigation Steps
- Identify package manager — npm, pip, dotnet, cargo, maven, etc.
- Run restore command —
npm install, pip install -r requirements.txt, dotnet restore, etc.
- Check for lock files —
package-lock.json, poetry.lock, Cargo.lock
- Identify private registries —
.npmrc, nuget.config, pip.conf
- Record failures — classify per taxonomy below
Common Restore Commands
| Ecosystem |
Command |
| Node.js |
npm install or yarn install or pnpm install |
| Python |
pip install -r requirements.txt or poetry install |
| .NET |
dotnet restore |
| Go |
go mod download |
| Rust |
cargo fetch |
| Java |
mvn dependency:resolve or gradle dependencies |
Scoring Rubric
| Score |
Criteria |
| 5 |
All dependencies restore cleanly on first attempt |
| 4 |
Minor warnings but functional — deprecated packages, peer dep warnings |
| 3 |
Partial success — some packages fail but core works |
| 2 |
Significant failures — private registry auth, version conflicts |
| 1 |
Most dependencies fail — broken lock file, missing registry |
| 0 |
Cannot restore any dependencies |
Phase 3: Build Success (Axis C)
Investigation Steps
- Find build command — from README,
package.json scripts, Makefile, etc.
- Run build —
npm run build, dotnet build, cargo build, make, etc.
- Capture output — record warnings and errors
- Classify failures — per taxonomy below
- Attempt fixes — if simple (missing env var, config), fix and retry
Common Build Commands
| Ecosystem |
Command |
| Node.js/TS |
npm run build or tsc |
| .NET |
dotnet build |
| Go |
go build ./... |
| Rust |
cargo build |
| Python |
python -m build or python setup.py build |
| Java |
mvn compile or gradle build |
Scoring Rubric
| Score |
Criteria |
| 5 |
Clean build, zero warnings |
| 4 |
Builds successfully with minor warnings |
| 3 |
Builds with significant warnings or non-critical errors suppressed |
| 2 |
Build fails but fixable (missing config, env vars, minor code issues) |
| 1 |
Build fails with deep issues (incompatible deps, missing system libs) |
| 0 |
Cannot determine how to build, or catastrophic failure |
Phase 4: Test Execution (Axis D)
Investigation Steps
- Find test command —
npm test, dotnet test, pytest, cargo test
- Run tests — capture pass/fail/skip counts
- Classify failures — infrastructure vs logic vs flaky
- Calculate pass rate — passing / (passing + failing)
- Note coverage if available
Common Test Commands
| Ecosystem |
Command |
| Node.js |
npm test or npx jest or npx vitest |
| .NET |
dotnet test |
| Python |
pytest or python -m unittest |
| Go |
go test ./... |
| Rust |
cargo test |
| Java |
mvn test or gradle test |
Scoring Rubric
| Score |
Criteria |
| 5 |
All tests pass, good coverage, fast execution |
| 4 |
>95% pass rate, minor flaky tests |
| 3 |
>80% pass rate, some infrastructure failures |
| 2 |
50–80% pass rate, significant issues |
| 1 |
<50% pass rate or tests barely run |
| 0 |
No tests exist, or test framework cannot execute |
Failure Taxonomy
Tag every failure encountered during evaluation:
| Tag |
Definition |
Example |
MISSING_TOOL |
Required tool/runtime not installed |
Node 18 needed, only 16 available |
AUTH_REQUIRED |
Credentials needed for private resource |
Private npm registry, Azure artifact feed |
ENV_CONFIG |
Missing environment variable or config file |
.env not present, appsettings.local.json missing |
VERSION_CONFLICT |
Dependency version incompatibility |
Peer dep mismatch, lockfile drift |
PLATFORM_SPECIFIC |
Works on one OS but not another |
Linux paths on Windows, missing system lib |
FLAKY_TEST |
Test passes/fails non-deterministically |
Timing-dependent, external service dependency |
Scoring & Tier Classification
Compute Total Score
Total = A + B + C + D (range: 0–20)
Tier Mapping
| Tier |
Score |
Interpretation |
| Excellent |
18–20 |
Ready for immediate productive work |
| Good |
14–17 |
Minor friction, workable with small fixes |
| Fair |
10–13 |
Significant setup needed before productive work |
| Poor |
6–9 |
Major blockers — investment required before engagement |
| Critical |
0–5 |
Not ready — fundamental issues must be resolved first |
Output Artifact
# Repository Readiness Report
**Repository:** <name>
**Date:** <date>
**Evaluator:** <who/what>
## Summary
| Axis | Score | Notes |
| ---- | ----- | ----- |
| A: Code Understanding | X/5 | <brief> |
| B: Dependency Restore | X/5 | <brief> |
| C: Build Success | X/5 | <brief> |
| D: Test Execution | X/5 | <brief> |
| **Total** | **X/20** | **Tier: <tier>** |
## Failures Encountered
| # | Phase | Tag | Description | Resolution |
| - | ----- | --- | ----------- | ---------- |
| 1 | B | AUTH_REQUIRED | Private npm registry needs token | Set NPM_TOKEN env var |
| 2 | C | ENV_CONFIG | Missing DATABASE_URL | Added to .env from .env.example |
## Recommendations
### Immediate (blocks productive work)
1. <fix>
### Short-term (improves experience)
1. <improvement>
### Nice-to-have
1. <suggestion>
Intervention Tracking
When you fix issues during evaluation, track them:
| Intervention |
Classification |
Impact on Score |
| Filled missing env var from example |
Config fix |
Score reflects post-fix state |
| Installed missing tool |
Setup fix |
Score reflects post-fix state |
| Fixed code to make build pass |
Code change |
Deduct 1 point from that axis |
| Skipped failing tests |
Workaround |
Score reflects skip (not pass) |
Autonomy penalty: If you had to modify source code (not config) to achieve a passing build/test, deduct 1 point from that axis. The repo should work without code changes for a new developer.
Troubleshooting Common Blockers
| Symptom |
Likely Cause |
Resolution |
ENOENT on install |
Wrong working directory |
Check for monorepo, find correct root |
401 Unauthorized on restore |
Private registry |
Check .npmrc, nuget.config, set auth token |
Cannot find module after install |
Missing build step |
Run build before test |
| Tests pass locally but timeout |
External service dependency |
Mock or skip integration tests |
| Build warns "deprecated" |
Old dependencies |
Usually safe to ignore for eval |
ENOMEM during build |
Large project, low memory |
Increase memory or build in parts |
Integration with Other Skills
| Skill |
Relationship |
architecture-audit |
Use readiness score to prioritize audit targets |
tech-debt-discovery |
Low readiness scores indicate tech debt |
testing-strategies |
Axis D failures feed test improvement planning |
bootstrap-learning |
Phase 1 aligns with bootstrap's Orient step |
1---2name: repository-readiness-eval3description: Evaluate a repository's readiness for AI-assisted development across 4 axes: code understanding, dependency restore, build success, and test execution. Use when onboarding to a new repo, assessing CI readiness, or validating that an AI agent can work effectively in a codebase.4---5
6# Repository Readiness Evaluation
7
8Systematic 4-axis assessment of whether a repository is ready for productive AI-assisted development — from code comprehension through successful test execution.
9
10## When to Use
11
12- Onboarding to an unfamiliar repository
13- Assessing if a codebase is AI-agent-ready
14- Validating CI/CD pipeline health
15- Pre-engagement quality check before committing to a project
16- Measuring improvement after fixing build/test issues
17
18---
19
20## The 4 Axes
21
22| Axis | Question | Score Range |
23| ---- | -------- | ----------- |
24| **A: Code Understanding** | Can you comprehend the project structure, tech stack, and architecture? | 0–5 |
25| **B: Dependency Restore** | Can you install/restore all dependencies successfully? | 0–5 |
26| **C: Build Success** | Does the project compile/build without errors? | 0–5 |
27| **D: Test Execution** | Do tests run and pass? | 0–5 |
28
29**Total**: 0–20 points → Tier classification (below)
30
31---
32
33## Phase 1: Code Understanding (Axis A)
34
35### Investigation Steps
36
371. **Read README** — does it explain setup, architecture, and conventions?
382. **Identify tech stack** — languages, frameworks, build system, package manager
393. **Map project structure** — entry points, module boundaries, config files
404. **Find build/run commands** — documented or discoverable from manifests
415. **Identify test framework** — what runs tests, where are they located
42
43### Scoring Rubric
44
45| Score | Criteria |
46| ----- | -------- |
47| 5 | Clear docs, standard structure, obvious entry points, well-organized |
48| 4 | Minor gaps but navigable — missing some docs, non-standard naming |
49| 3 | Understandable with effort — sparse docs, complex structure |
50| 2 | Confusing — unclear entry points, mixed concerns, minimal docs |
51| 1 | Barely comprehensible — no docs, non-standard everything |
52| 0 | Cannot determine project purpose or structure |
53
54---
55
56## Phase 2: Dependency Restore (Axis B)
57
58### Investigation Steps
59
601. **Identify package manager** — npm, pip, dotnet, cargo, maven, etc.
612. **Run restore command** — `npm install`, `pip install -r requirements.txt`, `dotnet restore`, etc.
623. **Check for lock files** — `package-lock.json`, `poetry.lock`, `Cargo.lock`
634. **Identify private registries** — `.npmrc`, `nuget.config`, `pip.conf`
645. **Record failures** — classify per taxonomy below
65
66### Common Restore Commands
67
68| Ecosystem | Command |
69| --------- | ------- |
70| Node.js | `npm install` or `yarn install` or `pnpm install` |
71| Python | `pip install -r requirements.txt` or `poetry install` |
72| .NET | `dotnet restore` |
73| Go | `go mod download` |
74| Rust | `cargo fetch` |
75| Java | `mvn dependency:resolve` or `gradle dependencies` |
76
77### Scoring Rubric
78
79| Score | Criteria |
80| ----- | -------- |
81| 5 | All dependencies restore cleanly on first attempt |
82| 4 | Minor warnings but functional — deprecated packages, peer dep warnings |
83| 3 | Partial success — some packages fail but core works |
84| 2 | Significant failures — private registry auth, version conflicts |
85| 1 | Most dependencies fail — broken lock file, missing registry |
86| 0 | Cannot restore any dependencies |
87
88---
89
90## Phase 3: Build Success (Axis C)
91
92### Investigation Steps
93
941. **Find build command** — from README, `package.json` scripts, `Makefile`, etc.
952. **Run build** — `npm run build`, `dotnet build`, `cargo build`, `make`, etc.
963. **Capture output** — record warnings and errors
974. **Classify failures** — per taxonomy below
985. **Attempt fixes** — if simple (missing env var, config), fix and retry
99
100### Common Build Commands
101
102| Ecosystem | Command |
103| --------- | ------- |
104| Node.js/TS | `npm run build` or `tsc` |
105| .NET | `dotnet build` |
106| Go | `go build ./...` |
107| Rust | `cargo build` |
108| Python | `python -m build` or `python setup.py build` |
109| Java | `mvn compile` or `gradle build` |
110
111### Scoring Rubric
112
113| Score | Criteria |
114| ----- | -------- |
115| 5 | Clean build, zero warnings |
116| 4 | Builds successfully with minor warnings |
117| 3 | Builds with significant warnings or non-critical errors suppressed |
118| 2 | Build fails but fixable (missing config, env vars, minor code issues) |
119| 1 | Build fails with deep issues (incompatible deps, missing system libs) |
120| 0 | Cannot determine how to build, or catastrophic failure |
121
122---
123
124## Phase 4: Test Execution (Axis D)
125
126### Investigation Steps
127
1281. **Find test command** — `npm test`, `dotnet test`, `pytest`, `cargo test`
1292. **Run tests** — capture pass/fail/skip counts
1303. **Classify failures** — infrastructure vs logic vs flaky
1314. **Calculate pass rate** — passing / (passing + failing)
1325. **Note coverage** if available
133
134### Common Test Commands
135
136| Ecosystem | Command |
137| --------- | ------- |
138| Node.js | `npm test` or `npx jest` or `npx vitest` |
139| .NET | `dotnet test` |
140| Python | `pytest` or `python -m unittest` |
141| Go | `go test ./...` |
142| Rust | `cargo test` |
143| Java | `mvn test` or `gradle test` |
144
145### Scoring Rubric
146
147| Score | Criteria |
148| ----- | -------- |
149| 5 | All tests pass, good coverage, fast execution |
150| 4 | >95% pass rate, minor flaky tests |
151| 3 | >80% pass rate, some infrastructure failures |
152| 2 | 50–80% pass rate, significant issues |
153| 1 | <50% pass rate or tests barely run |
154| 0 | No tests exist, or test framework cannot execute |
155
156---
157
158## Failure Taxonomy
159
160Tag every failure encountered during evaluation:
161
162| Tag | Definition | Example |
163| --- | ---------- | ------- |
164| `MISSING_TOOL` | Required tool/runtime not installed | Node 18 needed, only 16 available |
165| `AUTH_REQUIRED` | Credentials needed for private resource | Private npm registry, Azure artifact feed |
166| `ENV_CONFIG` | Missing environment variable or config file | `.env` not present, `appsettings.local.json` missing |
167| `VERSION_CONFLICT` | Dependency version incompatibility | Peer dep mismatch, lockfile drift |
168| `PLATFORM_SPECIFIC` | Works on one OS but not another | Linux paths on Windows, missing system lib |
169| `FLAKY_TEST` | Test passes/fails non-deterministically | Timing-dependent, external service dependency |
170
171---
172
173## Scoring & Tier Classification
174
175### Compute Total Score
176
177```text
178Total = A + B + C + D (range: 0–20)
179```
180
181### Tier Mapping
182
183| Tier | Score | Interpretation |
184| ---- | ----- | -------------- |
185| **Excellent** | 18–20 | Ready for immediate productive work |
186| **Good** | 14–17 | Minor friction, workable with small fixes |
187| **Fair** | 10–13 | Significant setup needed before productive work |
188| **Poor** | 6–9 | Major blockers — investment required before engagement |
189| **Critical** | 0–5 | Not ready — fundamental issues must be resolved first |
190
191---
192
193## Output Artifact
194
195```markdown
196# Repository Readiness Report
197
198**Repository:** <name>
199**Date:** <date>
200**Evaluator:** <who/what>
201
202## Summary
203
204| Axis | Score | Notes |
205| ---- | ----- | ----- |
206| A: Code Understanding | X/5 | <brief> |
207| B: Dependency Restore | X/5 | <brief> |
208| C: Build Success | X/5 | <brief> |
209| D: Test Execution | X/5 | <brief> |
210| **Total** | **X/20** | **Tier: <tier>** |
211
212## Failures Encountered
213
214| # | Phase | Tag | Description | Resolution |
215| - | ----- | --- | ----------- | ---------- |
216| 1 | B | AUTH_REQUIRED | Private npm registry needs token | Set NPM_TOKEN env var |
217| 2 | C | ENV_CONFIG | Missing DATABASE_URL | Added to .env from .env.example |
218
219## Recommendations
220
221### Immediate (blocks productive work)
2221. <fix>
223
224### Short-term (improves experience)
2251. <improvement>
226
227### Nice-to-have
2281. <suggestion>
229```
230
231---
232
233## Intervention Tracking
234
235When you fix issues during evaluation, track them:
236
237| Intervention | Classification | Impact on Score |
238| ------------ | -------------- | --------------- |
239| Filled missing env var from example | Config fix | Score reflects post-fix state |
240| Installed missing tool | Setup fix | Score reflects post-fix state |
241| Fixed code to make build pass | Code change | **Deduct 1 point from that axis** |
242| Skipped failing tests | Workaround | Score reflects skip (not pass) |
243
244**Autonomy penalty**: If you had to modify source code (not config) to achieve a passing build/test, deduct 1 point from that axis. The repo should work without code changes for a new developer.
245
246---
247
248## Troubleshooting Common Blockers
249
250| Symptom | Likely Cause | Resolution |
251| ------- | ------------ | ---------- |
252| `ENOENT` on install | Wrong working directory | Check for monorepo, find correct root |
253| `401 Unauthorized` on restore | Private registry | Check `.npmrc`, `nuget.config`, set auth token |
254| `Cannot find module` after install | Missing build step | Run build before test |
255| Tests pass locally but timeout | External service dependency | Mock or skip integration tests |
256| Build warns "deprecated" | Old dependencies | Usually safe to ignore for eval |
257| `ENOMEM` during build | Large project, low memory | Increase memory or build in parts |
258
259---
260
261## Integration with Other Skills
262
263| Skill | Relationship |
264| ----- | ------------ |
265| `architecture-audit` | Use readiness score to prioritize audit targets |
266| `tech-debt-discovery` | Low readiness scores indicate tech debt |
267| `testing-strategies` | Axis D failures feed test improvement planning |
268| `bootstrap-learning` | Phase 1 aligns with bootstrap's Orient step |
gabrielmoreira