feat(skill): enhance /architect persona and scoring#832
Conversation
Analyze Claude Code v2.1.88 architecture (all 17 episodes from claude-reviews-claude) to extract 22 transferable patterns for codegraph. Separate report identifies 11 concrete MCP integration hacks from source analysis — alwaysLoad, searchHint, readOnlyHint annotations — to make codegraph a first-class tool inside Claude Code.
- Add architect persona holding enterprise-grade bar regardless of project stage - Add dual-lens scoring: Current State vs State of the Art side by side, with gap analysis - Move audit output from docs/architecture/ to generated/architecture/ (single location) - Remove old audit from docs/architecture/ (already in generated/)
Greptile SummaryThis PR enhances the Key changes:
Confidence Score: 5/5Safe to merge — all P0/P1 ADR path issues are resolved; only a minor P2 style suggestion remains. The previously flagged ADR path regressions (three occurrences) were fully fixed in cc97456. The generated/architecture/ consolidation for audit output is correct, and the audit history is preserved in git. The only remaining observation is a minor style improvement to branch from origin/main instead of local main in Phase 8, which does not block merge. No files require special attention after the ADR path fix. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
P0["Phase 0: /worktree isolation"] --> P1
P1["Phase 1: Setup\npackage.json · date · SHA\nCheck generated/architecture/ for prev audits\nRead ADRs from docs/architecture/decisions/\ncodegraph build --no-incremental"] --> P2
P2["Phase 2: Structural Census\nstats · structure · triage · dead · cycles · map · complexity"] --> P3
P3["Phase 3: Layer-by-Layer Critique\nAbstraction · Coupling · SotA Comparison\nScalability · Correctness · ADR Compliance"] --> P4
P4["Phase 4: Cross-Cutting Concerns\nType Safety · Errors · Tests · Dual Engine\nDeps · Security · API · Docs"] --> P5
P5["Phase 5: Competitive Verification\nFetch READMEs · Cross-check source\nVerified comparison table"] --> P6
P6["Phase 6: Strategic Verdict\nReason to exist · Flaws · Moat\nKill List · Build vs Buy · Roadmap"] --> P7
P7["Phase 7: Write and Save\ngenerated/architecture/AUDIT_vVER_DATE.md\nAdd Changes Since Last Audit section"] --> P8
P8["Phase 8: Commit and PR\ngit checkout -b audit-branch origin/main\ngit add generated/architecture/ ...\ngit commit and push and gh pr create"]
Reviews (2): Last reviewed commit: "fix(skill): restore ADR lookup path to d..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
.claude/skills/architect/SKILL.md
Outdated
| 3. Check `docs/architecture/` for previous audit files | ||
| 4. **Read all ADRs in `docs/architecture/decisions/`.** These are the project's settled architectural decisions. Read every file — they document rationale, trade-offs, alternatives considered, and trajectory. The audit must evaluate the codebase *against* these decisions: are they being followed? Are the stated trade-offs still accurate? Has anything changed that invalidates the rationale? | ||
| 3. Check `generated/architecture/` for previous audit files | ||
| 4. **Read all ADRs in `generated/architecture/decisions/`.** These are the project's settled architectural decisions. Read every file — they document rationale, trade-offs, alternatives considered, and trajectory. The audit must evaluate the codebase *against* these decisions: are they being followed? Are the stated trade-offs still accurate? Has anything changed that invalidates the rationale? |
There was a problem hiding this comment.
The path was changed from docs/architecture/decisions/ to generated/architecture/decisions/, but no ADRs exist under generated/architecture/decisions/. The only ADR in the repo is at docs/architecture/decisions/001-dual-engine-architecture.md. Running git ls-files generated/architecture/decisions/ returns empty.
As a result, every future /architect run will silently skip ADR reading in Phase 1, and the ADR compliance review in Phase 3 will find nothing to evaluate.
The previous audits were correctly consolidated to generated/architecture/ (those are generated artefacts), but ADRs are design-decision records that belong in docs/ and are committed to git — they are not generated output. Updating this path breaks the audit's ability to validate ADR compliance.
| 4. **Read all ADRs in `generated/architecture/decisions/`.** These are the project's settled architectural decisions. Read every file — they document rationale, trade-offs, alternatives considered, and trajectory. The audit must evaluate the codebase *against* these decisions: are they being followed? Are the stated trade-offs still accurate? Has anything changed that invalidates the rationale? | |
| 4. **Read all ADRs in `docs/architecture/decisions/`.** These are |
There was a problem hiding this comment.
Fixed. Reverted all three ADR lookup paths back to docs/architecture/decisions/ in commit cc97456. The consolidation to generated/architecture/ was correct for audit output, but ADRs are committed design-decision records that belong in docs/. Verified that docs/architecture/decisions/001-dual-engine-architecture.md exists and generated/architecture/decisions/ does not.
.claude/skills/architect/SKILL.md
Outdated
| - Does the implementation match the decisions documented in `generated/architecture/decisions/`? | ||
| - Are the trade-offs described in ADRs still accurate given the current code? | ||
| - Has the codebase drifted from any stated trajectory? If so, is that drift justified or accidental? |
There was a problem hiding this comment.
Phase 3-F repeats the incorrect generated/architecture/decisions/ path. This is a second occurrence of the same mismatch — both must be corrected together to avoid the skill skipping ADR compliance checks.
| - Does the implementation match the decisions documented in `generated/architecture/decisions/`? | |
| - Are the trade-offs described in ADRs still accurate given the current code? | |
| - Has the codebase drifted from any stated trajectory? If so, is that drift justified or accidental? | |
| - Does the implementation match the decisions documented in `docs/architecture/decisions/`? | |
| - Are the trade-offs described in ADRs still accurate given the current code? | |
| - Has the codebase drifted from any stated trajectory? If so, is that drift justified or accidental? | |
| - Are there architectural decisions that *should* have an ADR but don't? |
There was a problem hiding this comment.
Fixed in the same commit (cc97456). This second occurrence at Phase 3-F is now reverted to docs/architecture/decisions/.
.claude/skills/architect/SKILL.md
Outdated
| - Executive summary (1 paragraph, brutally honest) | ||
| - Scorecard (each dimension rated 1-10 with justification) | ||
| - **ADR compliance review** — for each ADR in `docs/architecture/decisions/`, assess whether the codebase follows the decision, whether the stated trade-offs are still valid, and whether any drift has occurred. Flag missing ADRs for decisions that exist in code but aren't documented | ||
| - **ADR compliance review** — for each ADR in `generated/architecture/decisions/`, assess whether the codebase follows the decision, whether the stated trade-offs are still valid, and whether any drift has occurred. Flag missing ADRs for decisions that exist in code but aren't documented |
There was a problem hiding this comment.
The deliverable spec also references generated/architecture/decisions/ for the ADR compliance review. This is the third occurrence — it should be docs/architecture/decisions/ to match where ADRs actually live.
| - **ADR compliance review** — for each ADR in `generated/architecture/decisions/`, assess whether the codebase follows the decision, whether the stated trade-offs are still valid, and whether any drift has occurred. Flag missing ADRs for decisions that exist in code but aren't documented | |
| - **ADR compliance review** — for each ADR in `docs/architecture/decisions/`, assess whether the codebase follows the decision, whether the stated trade-offs are still valid, and whether any drift has occurred. Flag missing ADRs for decisions that exist in code but aren't documented |
There was a problem hiding this comment.
Fixed in the same commit (cc97456). Third occurrence in the Audit Structure section is now reverted to docs/architecture/decisions/.
| @@ -40,8 +59,8 @@ Run `/worktree` to get an isolated copy of the repo. `CLAUDE.md` mandates this f | |||
| ### Phase 1 — Setup | |||
There was a problem hiding this comment.
Step 3 now checks generated/architecture/ for previous audits — this is correct and consistent with the consolidation goal. Just confirming this step is fine on its own; the issue is in step 4 immediately below it.
There was a problem hiding this comment.
Acknowledged. Step 3 (generated/architecture/ for previous audits) is correct as-is — those are generated output. The fix only targets step 4 and the other two ADR references.
The output consolidation to generated/architecture/ was correctly applied to audit output paths, but incorrectly also changed ADR lookup references. ADRs are committed design-decision records that live in docs/architecture/decisions/, not generated output.
carlos-alm
force-pushed
the
docs/claude-code-architecture-analysis
branch
from
cc97456 to
e5fd2fb
Compare
1 participant
Summary
generated/architecture/only (removedocs/architecture/copy)Test plan
/architectand verify persona tone and dual-lens scorecard formatgenerated/architecture/