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:

Understand core principles: Read humaninloop:authoring-constitution for the Three-Part Principle Rule (Enforcement, Testability, Rationale)
Know RFC 2119 keywords: See RFC-2119-KEYWORDS.md in humaninloop:authoring-constitution
Understand SYNC IMPACT format: See SYNC-IMPACT-FORMAT.md in humaninloop:authoring-constitution
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:

Read codebase analysis - Look for "Strengths to Preserve" section
Identify patterns - Naming conventions, architecture patterns, error formats
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