sshah03

It's not perfect, but it's helped so far.

I had built a tool called perspica (https://github.com/sshah03/perspica) for semantic PR diffing, and in it I built in the ability to get LLM generated explanations of the major changes in the PR, architecture changes, etc... Along with interactive examples, and quizzes to test if you understand the concepts behind it, to help keep up with AI code changes. You can see some of its sample generations on PRs of popular public repos here: https://sshah03.github.io/perspica/

I spent a lot of time iteratively running examples on a ton of projects and PRs and modifying the prompt to help generate diagrams and questions I felt were actually useful.

One of the key learnings for anyone doing anything similar, at least with the 5.5 family of models, is that when you run on a few cases, you might feel the need to get very specific on how to solve for common scenarios etc... And any time I tried this the results got worse. It seems to like well written general guidelines, and the models are so capable now that the rest gets handled pretty well. Similarly, trying to build in error detection into the initial prompt works much worse than an adversarial pass (even with the same model), but obviously this slows the whole thing down ... so I'm still trying to work out how to balance that.

I figured rather than force people to use my whole tool for that, I'd extract what I learned works well into a claude code plugin/skill that can do the explanation/quiz part of what perspica does and store it as artifacts on the users Claude Code account, which is what this skill and repo is.

I'd love to hear where the explanations miss or the diagrams get something wrong so I can keep working on improving it for everyone. I considered not posting it, since it was just a Claude skill, but I'm interested in using peoples experiences with it to improve it, since getting something that works well for the diagrams generically has proven to be a bit tougher than I expected.