Skip to content

feat(skills): add Pythonic code guidance - #1095

Merged
phernandez merged 1 commit into
mainfrom
codex/pythonic-code
Jul 18, 2026
Merged

feat(skills): add Pythonic code guidance#1095
phernandez merged 1 commit into
mainfrom
codex/pythonic-code

Conversation

@phernandez

@phernandez phernandez commented Jul 18, 2026

Copy link
Copy Markdown
Member

Why

The recent local/cloud runtime consolidation made Basic Memory more capable, but it also exposed how easily portable Python can accumulate protocol towers, helper chains, misleading ownership names, and duplicated source-of-truth assumptions.

We want a shared review and implementation lens for code that is clear to both human and AI contributors: Pythonic without being clever, explicit about domain authority, and conservative about abstraction.

What Changed

  • add the /pythonic-code skill with write, refactor, and review modes
  • prefer functions and typed values before hierarchies, while retaining concrete classes and narrow protocols for real state and runtime boundaries
  • add docs/DOMAIN_MODEL.md to define projects, notes, entities, observations, relations, NoteContent, identity, ownership, and local versus DB-first authority
  • expand the engineering style guide with an explicit abstraction budget and private-helper-sprawl guidance
  • point AGENTS.md at the domain model and summarize the new house style

Implementation Details

This is guidance rather than a mechanical style mandate. Correctness, compatibility, and existing repository conventions remain higher priority than applying an idiom.

The domain model keeps Markdown as the canonical product representation while distinguishing durable local file authority from the accepted NoteContent state used during DB-first materialization.

Testing

  • uv run python /Users/phernandez/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/pythonic-code — passed
  • just package-check — passed
  • just agent-harness-check — passed
  • git diff --cached --check — passed before commit

Risks / Follow-ups

No runtime behavior changes.

Follow-up cleanup is tracked in:

These should land incrementally rather than turning this PR into a broad refactor.

Signed-off-by: phernandez <paul@basicmachines.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant