Managing Context

How to capture, organize, and use the knowledge that drives everything. Reference: METHOD.md for full methodology.

Why Context Is Everything

Context is the most valuable asset in any project. More valuable than the code, more valuable than the designs, more valuable than the plans.

Why? Because good context can regenerate everything else. Give an AI the right context — the business rules, the constraints, the design principles, the decision history — and it can rebuild the code. But give an AI the code without context, and it has no idea why the code works the way it does, what trade-offs were made, or what constraints it must respect.

Context is the fuel for every AI interaction. The quality of AI-generated output is directly proportional to the quality of context provided.

Types of Context

Business Rules

Domain knowledge that governs how the product or project behaves. These are facts about the world the project operates in.

Examples:

• "Subscriptions auto-renew unless cancelled 48 hours before billing date"
• "IV therapy appointments require 24-hour advance booking"
• "Michigan townships hold annual meetings on the last Saturday in March"
• "Patients must have a physician order before receiving IV therapy"

Business rules are not opinions or preferences — they are constraints from the domain. They don't change because we want them to. They change when the domain changes (new regulations, new business model, new stakeholder requirements).

Design Principles

Patterns and standards that apply across the project. These are choices that have been made about how things should work.

Examples:

• "All API responses use JSON:API format"
• "Mobile-first, progressive enhancement"
• "Every user action must complete in under 2 seconds"
• "Write in active voice, at an 8th-grade reading level"
• "Brand tone is smart but irreverent — professional without being corporate"

Design principles are decisions that have been elevated to standards. They started as individual Decisions and proved valuable enough to apply broadly.

Constraints

Hard limits that cannot be violated. These come from external forces: regulations, budgets, timelines, technical limitations, contractual obligations.

Examples:

• "Must comply with HIPAA for all patient data"
• "Total budget for Phase 1 is $25,000"
• "Must launch before Q3 board meeting (September 15)"
• "Cannot use AWS — existing infrastructure is on Azure"
• "Client's current website is on WordPress — migration must be seamless"

Constraints are non-negotiable within their scope. Unlike design principles (which are chosen), constraints are imposed. The team's job is to deliver outcomes within them.

Constraint vs Invariant — When to Use Which

A Context.constraint is passive documentation of a hard limit that applies to your project. Use this doc when you want to record a constraint as part of project context: HIPAA applies, budget is $25K, the launch deadline is September 15.

An Invariant is an enforced standing constraint with pass/fail status. It has an enforcement mechanism (compile / deploy / AI-verified / manual gate) and surfaces violations as Attention Alerts in the Signal layer. Use Invariants for things that MUST stay true while work flows: HIPAA encryption is enforced on every PHI write, brand voice is checked on every published post, audit-trail entries are required on every record mutation.

The shorthand: Context.constraint says "this limit exists." An Invariant says "this limit is being enforced right now, and here is its health status." Constraints inform the work. Invariants gate the work.

See INVARIANTS.md for the full Invariant primitive spec, field table, examples, and anti-patterns (including the common failure mode of writing a standing rule as a Context.constraint and hoping people read it).

Requirements

What the stakeholder asked for, captured in their words. Requirements are the raw input before they become Outcomes.

Examples:

• "We need customers to be able to book online without calling us"
• "I want to see how many appointments we had this month vs. last month"
• "The website should feel premium — not like a medical clinic, more like a spa"
• "We need to track which nurse did which appointment for liability purposes"

Requirements are preserved as-is even after being decomposed into Outcomes. The original words matter — they capture intent that structured Outcomes might miss.

Prompt Patterns

Reusable instructions for AI tools. These are templates and conventions for getting consistent, high-quality output from AI.

Examples:

• "When generating React components, use functional components with TypeScript, shadcn/ui for UI elements, and Tailwind for styling"
• "When writing API endpoints, follow the tRPC router pattern in API-PATTERNS.md"
• "When drafting customer communications, use the brand voice: warm, professional, concise"

Prompt patterns are context that feeds other AI interactions. They're what make the difference between generic AI output and output that fits the project.

Decision History

Automatically populated from the Decision Log. A searchable archive of every choice made and why.

This is not written manually — it flows from Decisions. It exists as Context so that when someone asks "why does the system work this way?", the answer is findable.

Reference Material

External documents that inform the work but aren't authored by the team: contracts, third-party API docs, industry standards, competitor analysis, research papers, brand guides.

Reference material is stored, not summarized. The original document is preserved alongside any annotations or key takeaways the team has added.

How to Write Good Context

Rule 1: Write It When You Learn It

The moment you discover a business rule, encounter a constraint, or make a design decision — write it down immediately. Context that stays in someone's head is context that will be lost.

Rule 2: One Idea Per Entry

Each Context entry should cover one discrete piece of knowledge. Don't combine "API response format" with "authentication approach" in a single entry. Separate entries are searchable, linkable, and individually updatable.

Rule 3: Write for Someone Who Wasn't There

The reader of Context may be a new team member, a future version of yourself, or an AI agent. Write with enough background that the entry is understandable without additional verbal explanation.

Rule 4: Include the "Why"

Don't just state the rule — explain why it exists.

• ❌ "Use UTC for all timestamps"
• ✅ "Use UTC for all timestamps. The platform serves multiple time zones, and local time conversions happen only in the UI layer. This prevents timezone bugs in scheduling logic and simplifies database queries."

Rule 5: Update When Things Change

Context is living. When a business rule changes, when a constraint is lifted, when a design principle evolves — update the entry. Don't create a new entry and leave the old one intact without marking it obsolete.

Rule 6: Tag and Link

Every Context entry should be:

• Tagged with relevant labels (project name, domain area, technology)
• Linked to the Outcomes it informs and the Decisions it's related to
• Typed correctly (business rule, constraint, design principle, etc.)

Using Context

Before Building Anything

Before starting Build on any Outcome, the builder (human or AI) should:

1. Read all Context linked to the Outcome
2. Read the relevant project-wide Context (design principles, constraints, prompt patterns)
3. Check Decision History for any related decisions

This is not optional. Building without context produces code that works in isolation but doesn't fit the system.

When Making Decisions

Before making any Decision, check:

1. Is there existing Context that informs this choice? (Constraints? Business rules?)
2. Are there precedent Decisions in the history?
3. What Context will change depending on which option we choose?

When AI Is Generating Output

Always provide relevant Context to AI tools. The pattern is:

Here is the context for this task:
[Business rules that apply]
[Design principles that apply]
[Constraints that apply]
[Relevant decisions that have been made]
[Prompt patterns for this type of work]

Now, given this context: [specific instruction]

The quality of AI output is limited by the quality of context provided.

When Onboarding

New team members read Context before anything else. The Context Hub IS the onboarding documentation. If a new person can't understand the project from Context alone, the Context is incomplete.

Context Organization

By Scope

• Workspace-wide Context: Applies to everything (company brand voice, shared technology standards, compliance requirements)
• Project-specific Context: Applies to one project (client requirements, project constraints, project-specific design decisions)

By Lifecycle

• Stable Context: Rarely changes (business rules from regulations, long-term design principles)
• Evolving Context: Updated as the project progresses (architecture decisions, scope boundaries)
• Temporal Context: Relevant to a specific phase (Phase 1 constraints that won't apply in Phase 2)

By Audience

• Internal Context: For the team only (implementation details, internal trade-offs)
• Publishable Context: Can be shared with clients or the public (via Docs module or Portal)

Common Mistakes