team-diagnose
Skill145 starsChanged 21 days agoMITView on GitHub
Use when the team context did not appear at session start, a skill failed to trigger, the install behaves unexpectedly, or someone asks why a session ran without team rules — walks the failure chain with commands and evidence before any conclusion.
In this repository48 other files it gives its agents.
- architect-analyzeSkill
- architect-bootSkill
- architect-clarifySkill
- architect-implementSkill
- architect-initSkill
- architect-specifySkill
- writing-skillsSkill
- change-bootSkill
- change-clarifySkill
- change-initSkill
- change-publishSkill
- change-specifySkill
- evals-analyzeSkill
- evals-clarifySkill
- evals-implementSkill
- evals-initSkill
- evals-specifySkill
- evals-validateSkill
- factory-cleanSkill
- factory-initSkill
- factory-intentSkill
- factory-learnSkill
- factory-missionSkill
- factory-orchestratorSkill
- factory-queueSkill
- factory-releaseSkill
- factory-reviewSkill
- factory-runbookSkill
- factory-setupSkill
- factory-ticketsSkill
- mission-briefSkill
- product-analyzeSkill
- product-bootSkill
- product-clarifySkill
- product-implementSkill
- product-initSkill
- product-roadmapSkill
- product-specifySkill
- team-bootSkill
- team-constitutionSkill
- team-discoverSkill
- team-initSkill
- team-levelupSkill
- team-repairSkill
- team-setupSkill
- team-skillsSkill
- workspaceSkill
- tech-radar-bootSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Run the checks in order — stop at the first failure, fix, re-run:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
team-diagnose
Scope rule: scripts stay skill-local — never source a script from another skill. For another skill's operations, invoke that skill (e.g.
architect-clarify,product-clarify,team-boot) via the Skill tool; for its documents, follow theRequiresline.scripts/andreferences/below are relative to this skill.{REPO_ROOT}denotes the project root (where.adlc/lives).
Overview
Evidence-first diagnosis of broken adlc-team-skills wiring. The chain has exactly five links, each checkable with one command — a diagnosis without command output is a guess, and guesses get pasted into bug reports.
Boundary: this repo owns .events.json and the boot scripts' output.
The injection side (dispatchers, generated per-agent plugins) is owned by
adlc-cli — the
docs/event-hook-contract.md file in the adlc-team-skills repo draws the
line. Diagnose up to it, then route.
When to Use
- Team context missing at session start (no
Team Context & Decisionssection). - A rule that should have matched didn't load.
- Install behaves unexpectedly after an update.
When NOT to use: for application bugs unrelated to the team-context chain, or for skill behavior debates (that's a goldset/eval question).
Core Process
Run the checks in order — stop at the first failure, fix, re-run:
| # | Symptom area | Check (run it) | Green means |
| 1 | Not configured | cat .adlc/init-options.json | A team_ai_directives path that exists |
| 2 | Missing tool | command -v jq | jq on PATH (skills registry needs it) |
| 3 | Broken handler | Invoke the team-boot skill | The directives index on stdout, wrapped in EXTREMELY_IMPORTANT |
| 4 | Stale install | pytest tests/unit/test_generated_artifacts_sync.py -q (in the skills repo) or compare skills/**/SKILL.md vs installed skill names | Mirror matches source |
| 5 | Injection side | Generated plugin present and loaded for the agent? | If 1–4 are green and the session still lacks context → adlc-cli's territory — file there with the outputs of checks 1–4 attached |
For "a rule didn't load" specifically: confirm the session began with the index (check 3's content), then check the task actually matched the rule's descriptor — on-demand pull is match-driven, not mind-reading.
Whole-loop check: scripts/acceptance-test.sh scratch-installs and
asserts the chain end-to-end (add --live for a real agent session).
Report format
For a bug report, include: the failing check number, the command, its
verbatim output, agent name/version, and how the repo was installed
(npx skills add vs adlc-cli). No scrubbed narrative — raw
output.
Red Flags
- Concluding before running a command — every check is one command.
- "Reinstall everything" before reading check 3's output.
- Blaming a skill's content when check 1–3 failed (config, not skills).
- Filing injection-side bugs in adlc-team-skills (check 5 routes them).
All of these mean: run the checks, then report.
Verification
A diagnosis is done when:
- Checks 1–4 each ran with output captured (or 5 routed with evidence)
- The failing link is named with its command output
- The report routes to the owning repo
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.