Skip to content

phel-lang/phel-pdo / .claude/skills/refactor-check

refactor-check

Verified

Analyze Phel source for clean-code issues and phel-pdo rule compliance (.claude/rules/*.md)

Refactor Check

Read and analyze the specified file(s) from $ARGUMENTS (default: src/pdo.phel + src/pdo/statement.phel).

phel-pdo is a thin idiomatic PDO wrapper, pure Phel, struct-based. There are no classes, no Gacela modules, no compiler phases - judge against the project rules, not OOP/SOLID.

API Design (.claude/rules/api-design.md)

CheckRule
One fn per methodOne Phel fn per exposed PDO method, kebab-case (lastInsertId → last-insert-id)
Arg orderWrapped struct first (conn/stmt), then PDO args in PHP order, then & [optional]
OptionalsDefault in body via (or x \PDO/DEFAULT), never overloads
Mutatorsexecute/bind-value/set-attribute return the wrapped struct (thread with ->)
Readsfetch/fetch-all/row-count/… return Phel-native data
Rows outEvery raw fetch routed through row->map (keys → keywords)
Params inUser maps/vectors run through phel->php before PDO
ErrorsRely on ERRMODE_EXCEPTION; never re-wrap \PDOException
EncapsulationNo public fn exposes raw \PDO / \PDOStatement

Clean Code

  • Naming: kebab-case, intention-revealing? defn-/def- for non-public?
  • Functions: Small? One responsibility? Threading (->, ->>) where it clarifies?
  • Docstrings: Public fns carry a terse :doc one-liner? Return-type tag reflects the underlying PDO type?
  • Comments: ; inline, ;; standalone, ;;; section header? No commented-out forms left behind?
  • Purity: Pure functions only outside the PDO call sites; no globals?
  • Interop: Boundary crossed only via phel->php / php->phel, (php/-> (x :pdo) ...) / (php/-> (x :stmt) ...)?

Cross-File Hygiene

CheckRule
Namespacestatement.phel opens with (in-ns phel.pdo)
DeclaresNew cross-file decls via declare in src/pdo.phel before (load "pdo/statement")
API tablesREADME.md connection/statement tables list every public fn

Output Format

# Refactor Analysis: <file/directory>

## Summary
- **API Design Issues:** X
- **Clean Code Issues:** X
- **Cross-File Issues:** X

## Critical Issues (High Priority)
### [API] <fn> leaks raw \PDOStatement
**File:** `src/pdo/statement.phel:42`
**Problem:** ...
**Suggestion:** ...

## Moderate Issues (Medium Priority)
...

## Minor Issues (Low Priority)
...

## Recommended Refactoring Steps
1. ...
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 321kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 321kUpdated Claude CodeCodexVerifiedInstall