governance-maintenance

name	governance-maintenance
description	Use for rankingdepadel.club governance edits, instruction version/date alignment, markdown rules, governance validation, changelog wording, and maintaining progressive disclosure between router docs and skills.

Governance Maintenance

Use this skill for governance markdown edits, instruction routing, validation, and ownership boundaries.

File Ownership

• docs/PROJECT_INSTRUCTIONS.md: ChatGPT conversational design and copy-paste pre-spec output only.
• AGENTS.md: minimal Codex router, authority, branch/spec safety, skill routing, and validation pointers.
• .codex/skills/: detailed Codex workflows and progressive disclosure.
• README.md: repository orientation and owner-doc pointers.
• CHANGELOG.md: shipped and unreleased outcomes.
• RELEASE.md: release flow and fallback tools.
• GitHub Issues: backlog and informal pre-spec intake.
• specs/: approved implementation specs and release records.

Progressive Disclosure Rules

• Keep always-loaded governance short.
• Keep AGENTS.md around 1,400-1,800 characters, with 2,000 as a practical ceiling unless a temporary router rule is clearly needed.
• When validation reports governance size drift, make at most one scoped compaction pass. If warnings remain, report them as follow-up work instead of cycling on character-count targets.
• Move detailed workflow behavior into task-triggered skills.
• Do not duplicate long rules between AGENTS.md, docs/PROJECT_INSTRUCTIONS.md, and skills.
• Keep each skill body around 2,500-5,000 characters; when a SKILL.md exceeds 7,000 characters, move optional detail into references or scripts.
• Keep skill count tied to distinct triggerable workflows. For this project, 10-15 skills is healthy; merge only when skills share the same trigger, owner decisions, and frequent read path.
• New governance rules need a clear owner file or skill; avoid scattering the same rule across multiple surfaces.
• When governance or skills depend on external docs, MCP tools, scripts, or bundled references, name the source of truth and the fallback order.
• Keep always-loaded router docs policy-level. Put detailed source lookup, fallback disclosure, and scope-limiting workflow inside task-triggered skills.
• Preserve user-authored text/style intent in governance and skill edits. Ask before changing wording or style rules when the user's intention is unclear.

Versioning and Validation

• Keep AGENTS.md metadata current for governance changes.
• Keep docs/PROJECT_INSTRUCTIONS.md metadata pinned to the latest successful release version and date, not to each AGENTS.md governance revision.
• When stable project facts, ChatGPT-facing boundaries, pre-spec handoff rules, or execution-split rules change, note whether docs/PROJECT_INSTRUCTIONS.md needs release-time updates instead of editing it on every governance change.
• Before finishing governance edits, explicitly check whether the change affects stable ChatGPT-facing project instructions; update release-pinned docs/PROJECT_INSTRUCTIONS.md only when the task is release preparation or release closure.
• Do not mirror transient Codex workflow detail into docs/PROJECT_INSTRUCTIONS.md; keep it to durable guidance that helps disconnected ChatGPT planning.
• Run python scripts/validate_governance.py after governance, router, project-instruction metadata, or validation-policy edits.
• For non-governance Markdown docs, run markdownlint only.
• Run markdownlint on changed Markdown files when available.
• Enforce MD022 and MD032; omit MD013 reports and do not reflow long lines only to satisfy line-length linting.
• Do not add markdownlint-disable directives unless explicitly requested.
• Preserve authoritative generated text unless a structural correction is required.

Workflow Error Feedback

• Treat errors surfaced during a Codex conversation as opportunities to improve the governance workflow or owning skills.
• Exclude expected TDD failures and red-green test signals from this rule unless they expose a workflow gap.
• At the end of the conversation, briefly call out any non-TDD error that suggests a durable governance or skill improvement, with a concrete follow-up suggestion when useful.
• Do not propose governance churn for isolated product bugs, flaky external systems, or already-covered instructions unless the observed failure shows the current workflow did not guide execution.

Markdown Style

• Keep new or rewritten Markdown light and schematic.
• Markdown remains the default governance format. Allow static HTML review artifacts when visual structure or interaction helps the user choose between alternatives, especially UI/UX display options; document whether HTML complements or replaces Markdown.
• Write proposal and review artifact chrome in English. User-facing UI copy inside mockups or UX examples may stay in Spanish when it represents product text.
• Write concise, specific Markdown, including skills. Avoid long grammar constructions, verbose setup, and repeated restatement.
• Prefer short sections, direct bullets, compact summaries, and no duplicate restatement.
• Preserve explicit user targets when documenting upgrades, migrations, or rewritten guidance. Do not silently substitute a "latest" target or widen the task beyond the stated request.
• If authoritative external guidance and repository behavior or governance disagree, state the conflict and stop before making broad rewrites.
• Active-work specs should capture only the scope, constraints, and checks needed for execution.
• Consolidated release files should be compact provenance summaries, not embedded copies of prior source files.
• Release changelog entries should use at most one concise bullet per stable product or workflow domain in each release, merging related specs and outcomes while avoiding verbose process detail.