brownfield-constitution

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