piighost: Skill for Claude Code

PIIGhost code style

Overview

PEP8 and ruff already enforce formatting (line length, import order, quotes, trailing commas). This skill captures the conventions that tooling does not enforce: how the maintainer prefers expressions, dispatch, and naming to be written. They are taste rules, gathered from review feedback.

Apply them whenever you write or refactor code. When a rule conflicts with an established local pattern, match the surrounding code and flag the tension rather than rewriting silently.

This skill grows. When the maintainer states a new preference during a review, add it here as a new numbered rule with an Avoid -> Prefer pair and a one-line why. Keep the existing entries; do not renumber on every edit.

Rules

1. Prefer a named local + or over a None-guard ternary

When falling back to a default and the falsy-but-not-None edge (e.g. the empty string) is irrelevant, bind a named local with or instead of an inline x if x is not None else y.

Avoid:

return {"text": redact_as if redact_as is not None else self.text, ...}
self.detections = detections if detections is not None else []

Prefer:

text = redact_as or self.text
return {"text": text, ...}

self.detections = detections or []

Why: the named local reads like a sentence and or is shorter. This holds for a constructor defaulting an optional argument to an empty collection too: self.x = arg or [], not the ternary. Only keep is not None when an empty/zero value must be preserved distinctly from the default, and add a comment saying so when you do.

2. Prefer a data-driven dict over an if/elif dispatch cascade

When selecting one of N things by a key, use a dict lookup, not a chain of if key == ...: return .... A dict is O(1), auditable at a glance, and adding a case is a single line.

Avoid:

def _resolve_lazy_detector(key):
    if key == "lazy:gliner2":
        from piighost.detector.gliner2 import Gliner2Detector
        return Gliner2Detector
    if key == "lazy:spacy":
        from piighost.detector.spacy import SpacyDetector
        return SpacyDetector
    raise KeyError(key)