# Create Principles Document

> Creates or updates PRINCIPLES.md from repository evidence and values. Use when a project needs to define, repair, or review the guiding principles that govern its decisions and behavior.

- Skill: `egohygiene/create-principles-document` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add egohygiene/create-principles-document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egohygiene/create-principles-document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: egohygiene (https://skillmd.com/u/egohygiene)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egohygiene/create-principles-document

---


# Create Principles Document

<!-- aether-continuity-disposition: reader-writer -->

## Repository continuity composition

For repository-scoped work, compose `maintain-repository-continuity` in
**Resume** mode before selecting work. After an authorized repository change
passes domain validation, compose **Refresh** and **Verify** immediately before
presenting the pull request, and include the reconciled root `CONTINUITY.md` in
the same change. A policy-permitted no-change or exemption result must be
documented instead of fabricating an edit.

- **Contribute:** Principles, tradeoffs, cited decisions, validation, and unresolved approval
- **Never claim:** That drafted principles are accepted policy without evidence

## Purpose

Create or update `PRINCIPLES.md` in conformance with `architecture-principles`.

Primary question:

> How should decisions be evaluated when multiple valid options exist?

## Use This Skill When

- the canonical document does not exist
- an existing document is incomplete or inconsistent
- upstream identity has changed
- repository architecture is being established or repaired

## Required Inputs

- PURPOSE.md
- VISION.md
- organizational values
- recurring historical trade-offs
- architectural and engineering experience
- existing policies and standards

Missing evidence must be recorded rather than invented.

## Workflow

1. Read purpose and vision.
2. Identify recurring decisions and tensions.
3. Convert durable lessons into heuristics.
4. Remove technology-specific language.
5. Test each principle against real trade-offs.
6. Identify conflicts and precedence.
7. Distinguish principles from policies and standards.
8. Validate memorability and applicability.

## Output Contract

Produce:

- `PRINCIPLES.md`
- governing specification identifier and version
- assumptions and unresolved questions
- validation results
- downstream review recommendations

## Constraints

- Preserve canonical terminology.
- Separate evidence from inference.
- Do not fabricate intent.
- Do not introduce implementation details outside the specification.
- Do not silently resolve contradictions.
- Do not claim completion when upstream artifacts are missing.

## Validation

Use `references/validation-checklist.md` and the acceptance criteria in
`architecture-principles`.

## Completion Criteria

- [ ] The governing specification is identified.
- [ ] Required upstream evidence has been read.
- [ ] The document answers its primary identity question.
- [ ] Non-responsibilities are respected.
- [ ] Assumptions and open questions are visible.
- [ ] Structural, semantic, relationship, and evidence checks pass.
- [ ] Downstream review needs are reported.