| name | code-quality-review |
| description | Review and improve Python code quality in SoulMap AI so typing, helper usage, exception handling, and repo tooling conventions stay consistent. |
Code quality review
Use this skill when reviewing or improving Python implementation quality in src/,
compatibility wrappers, tests/, or scripts/.
Do not use this skill for
Mission
Keep Python changes clear, typed, maintainable, and consistent with the repo's existing
tooling contract.
Sources to check first
pyproject.toml../rules/python-tooling.md../rules/source-character-safety.mddocs/engineering/DEV.md- the target Python files and nearby tests
What to look for
- stale or duplicated helper logic
- weak typing or type drift against repo conventions
- broad exception handling or hidden failure paths
- dead branches, unused fields, or wrappers that add no value
- local code that should use shared helpers in
src/soulmap/runtime/io/cli_payload.py or
src/soulmap/runtime/io/text_normalization.py
Workflow
- Read the target Python files and the closest tests first.
- Compare the implementation with
pyproject.toml and ../rules/python-tooling.md.
- Identify concrete quality issues that affect clarity, correctness, or maintenance.
- Make the smallest correct change that improves the code without widening scope.
- Update tests when the observable contract changes.
- Run the repo checks needed for the touched files.
Expected output
Findings
List the concrete code-quality issues first.
Fixes
Summarize the changes that improved type safety, helper usage, or readability.
Validation
State which checks were run and whether they passed.
Definition of done
The updated code should be:
- simpler or clearer than before
- aligned with repo tooling rules
- free of obvious duplicated logic
- covered by the right tests for the changed behavior
