brownfield-constitution

Brownfield Constitution Authoring

Overview

Write project constitutions for existing codebases using the Essential Floor + Emergent Ceiling approach. This skill extends humaninloop:authoring-constitution with brownfield-specific guidance that respects existing patterns while establishing governance.

The core insight: existing codebases have implicit conventions worth preserving (Emergent Ceiling) but may lack foundational governance in critical areas (Essential Floor). This skill helps codify both.

When to Use

Applicable when:

• Creating a constitution for an existing codebase (brownfield project)
• The codebase has existing patterns, conventions, or architecture worth preserving
• You need to establish governance without disrupting working code
• The user mentions "brownfield", "existing codebase", or "legacy project"
• Codifying implicit conventions into explicit, enforceable principles

When NOT to Use

• New project from scratch: REQUIRED alternative - Use humaninloop:authoring-constitution directly
• Codebase analysis not completed: REQUIRED prerequisite - Run humaninloop:analysis-codebase first
• Project too small for formal governance: Single-file scripts, prototypes do not need constitutions
• Validating existing constitution: OPTIONAL - Use humaninloop:validation-constitution

Prerequisites

REQUIRED: This skill extends humaninloop:authoring-constitution. Prerequisites for brownfield mode:

1. Understand core principles: Read humaninloop:authoring-constitution for the Three-Part Principle Rule (Enforcement, Testability, Rationale)
2. Know RFC 2119 keywords: See RFC-2119-KEYWORDS.md in humaninloop:authoring-constitution
3. Understand SYNC IMPACT format: See SYNC-IMPACT-FORMAT.md in humaninloop:authoring-constitution
4. Run codebase analysis: Execute humaninloop:analysis-codebase to understand existing patterns

Brownfield constitutions follow all rules from humaninloop:authoring-constitution, plus additional guidance for existing codebases.

• Essential Floor: Four NON-NEGOTIABLE categories every constitution MUST address
• Emergent Ceiling: Good patterns from the codebase worth codifying

Essential Floor (NON-NEGOTIABLE)

Every constitution MUST include principles for these four categories, regardless of codebase state:

Category	Minimum Requirements	Default Enforcement
Security	Auth at boundaries, secrets via env/secret managers, input validation, secret scanning in CI	Integration tests, code review, secret scanning tools
Testing	Automated tests exist, coverage ≥80% (configurable), ratchet rule (coverage MUST NOT decrease)	CI test gate, coverage threshold with warning/blocking levels
Error Handling	Explicit handling, RFC 7807 Problem Details format, correlation IDs in responses	Schema validation in tests, code review
Observability	Structured logging, correlation IDs, APM integration, no PII in logs	Config verification, log audit, APM dashboards

See references/ESSENTIAL-FLOOR.md for detailed requirements and example principles for each category.

Writing Essential Floor Principles:

• If codebase has the capability → Principle codifies existing pattern with enforcement
• If codebase lacks the capability → Principle states "MUST implement" with roadmap gap

Emergent Ceiling (FROM CODEBASE)

Beyond the essential floor, identify existing good patterns worth codifying:

1. Read codebase analysis - Look for "Strengths to Preserve" section
2. Identify patterns - Naming conventions, architecture patterns, error formats
3. Codify as principles - With enforcement mechanisms

See references/EMERGENT-CEILING-PATTERNS.md for the pattern library with examples.

Common Pattern Categories:

Pattern Category	What to Look For
Code Quality	Documentation requirements, API annotations, deprecation handling
Architecture	Layer rules, dependency injection, module boundaries
API Design	Response formats, versioning, pagination
Authorization	Role-based access, permission checks
Resilience	Retry policies, circuit breakers, timeouts
Configuration	Strongly-typed options, feature flags
Error Handling	Error display guidelines, data resilience
Observability	Log levels, context requirements, crash reporting
Product Analytics	Event categories, naming conventions, funnel tracking
Naming Conventions	File/class/variable naming, directory structure

Brownfield Constitution Structure

# [Project] Constitution

<!-- SYNC IMPACT REPORT -->

## Core Principles

### Essential Floor Principles
I. Security by Default
II. Testing Discipline
III. Error Handling Standards
IV. Observability Requirements

### Emergent Ceiling Principles
V. [Pattern from codebase]
VI. [Pattern from codebase]
...

## Technology Stack
[From codebase analysis]

## Quality Gates
[From codebase analysis + essential floor requirements]

## Governance
[Standard governance section]

## Evolution Notes

This constitution was created from brownfield analysis.

**Essential Floor Status** (from codebase-analysis.md):
| Category | Status | Gap |
|----------|--------|-----|
| Security | partial | GAP-001 |
| Testing | partial | GAP-002 |
| Error Handling | present | - |
| Observability | absent | GAP-003 |

See `.humaninloop/memory/evolution-roadmap.md` for improvement plan.

Brownfield Quality Checklist

Additional checks for brownfield constitutions (beyond standard checklist):

• All four essential floor categories have principles
• Existing good patterns identified and codified
• Gap references included where codebase lacks capability
• Technology stack matches codebase analysis
• Quality gates reflect current + target state
• Evolution Notes section documents brownfield context

After completing brownfield constitution, run validation using humaninloop:validation-constitution.

Common Mistakes

Mistake 1: Skipping Essential Floor Categories

Problem: Assuming the codebase "doesn't need" security or observability principles because it "seems simple" or "works fine."

Why it's wrong: Essential floor categories exist because these are areas where missing governance causes the most damage. A working codebase without security principles will eventually have a security incident.

Fix: Always include all four essential floor categories. If the codebase lacks capability in an area, write the principle with "MUST implement" and reference a roadmap gap.

Mistake 2: Codifying Bad Patterns from the Codebase

Problem: Treating all existing patterns as worth preserving. The emergent ceiling captures whatever is in the codebase, including anti-patterns.

Why it's wrong: Some patterns in existing codebases are historical accidents, workarounds, or technical debt. Codifying them as principles locks in bad practices.

Fix: Only codify patterns that are intentionally good. Ask: "Would I recommend this pattern for a new project?" If no, it's technical debt, not an emergent ceiling pattern.

Mistake 3: Skipping Codebase Analysis

Problem: Writing the brownfield constitution without first running humaninloop:analysis-codebase.

Why it's wrong: Without analysis, the process devolves into guessing about existing patterns. Good patterns worth preserving get missed and essential floor status assessments become inaccurate.

Fix: Always run codebase analysis first. The analysis output has "Strengths to Preserve" (emergent ceiling input) and gap identification (essential floor status).

Mistake 4: Writing Aspirational Instead of Enforceable Principles

Problem: Writing principles like "Code SHOULD be clean" or "Security SHOULD be considered" without concrete enforcement.

Why it's wrong: These principles are unenforceable and untestable. They provide no governance value and will be ignored.

Fix: Every principle needs the Three-Part Rule from humaninloop:authoring-constitution: specific behavior, enforcement mechanism, and rationale. "Security SHOULD be considered" becomes "Authentication MUST use JWT with rotation, enforced by middleware check, because centralized auth prevents bypass."

Mistake 5: Ignoring Evolution Notes

Problem: Creating the constitution without documenting the brownfield context and gap status.

Why it's wrong: Future maintainers won't know which principles reflect existing capability vs. aspirational targets. They can't prioritize improvements.

Fix: Always include the Evolution Notes section with essential floor status table and link to evolution roadmap. This makes gaps visible and actionable.

Related Skills

• REQUIRED: humaninloop:authoring-constitution - Core authoring (prerequisite)
• REQUIRED: humaninloop:analysis-codebase - Analyze existing codebase before writing
• OPTIONAL: humaninloop:validation-constitution - Quality validation (use after authoring)
• OPTIONAL: humaninloop:authoring-roadmap - Create evolution roadmap for identified gaps