SENAR Guide: Philosophy

This document expands on the SENAR Values and explains the six pillars that underpin the methodology.

SENAR Values

Context over Code — AI output quality is determined by input context quality. Invest in requirements, not in coding speed.
Verification over Speed — AI generates at machine speed. Correctness, not velocity, is the constraint.
Knowledge over Experience — AI has no memory between sessions. What’s not documented doesn’t exist for AI.
Enforcement over Agreement — Quality gates as automated code, not meetings people can skip.
Judgment over Keystrokes — Human attention on decisions (what to build, is it correct), not on typing code.

Pillar 1: Context-First (Quality at Input)

The quality of AI output is a direct function of input context quality.

The cascade principle: Quality is built at input, not checked at output. A defect in a Business Requirement propagates to all downstream System Requirements, Task Requirements, and ultimately to code. By the time a defective requirement reaches AI execution, it produces plausible-looking code that passes automated checks but solves the wrong problem. No amount of testing at the output (QG-2, QG-3) can catch a requirement that was wrong from the start.

This is why SENAR invests in requirement quality (QG-0, QG-1) before implementation begins — not as bureaucracy, but as the highest-leverage quality investment.

Requirements ARE context. A well-defined Business Requirement that decomposes into clear System Requirements and Task Requirements IS the primary input to AI-generated code quality. The requirement hierarchy (BR → SR → TR) is not paperwork — it is the structured context that determines whether AI produces correct output.

Context components:

Task goal and acceptance criteria (= Task Requirements)
Requirement links to parent Story/BR/SR (= traceability)
Architectural constraints and conventions
Relevant knowledge (decisions, dead ends, gotchas)
Examples and anti-patterns
Scope boundaries (what NOT to change)

Common failures:

Vibe prompting — vague instructions without structure. Appropriate for trivial tasks; dangerous for complex work.
Context dumping — flooding AI with unstructured information. Critical constraints get buried.
Implicit assumption — expecting AI to know conventions without documentation.
Ambiguous requirements — requirements that a human would clarify in conversation but AI interprets literally or hallucinates a resolution. Unlike human teams, AI does not ask “did you mean X or Y?” — it picks one silently.

Pillar 2: AI-First, Not AI-Only

The Supervisor’s primary mode is AI-directed work. Manual coding is a justified exception, not a prohibition.

The exception is recorded. Since revision 1.4, modifying an artifact by a route QG-0 does not precede is a Gate Bypass and is recorded as one, with justification, risk acknowledgment, remediation plan, and senior approval (Standard 8.6(j), 4.1). This does not make manual coding rarer or harder — it makes it visible. What is no longer available is doing it silently, and “preparing the context costs more than the fix” is a justification you write down, not a reason to skip writing one.

When manual intervention is appropriate. Since Standard 1.5 the answer is narrower than this Guide used to give, and the reason is dated rather than principled: the list below described what agents could not do when it was written, and models moved.

One case is recognized as substantive (Standard 4.1): an environment in which no agent can be run and there is nothing to switch to.

The cases this Guide used to list are not exceptions where an agent environment exists — each has an agent-side answer:

Case as it used to be listed	What to do instead
Micro-fix (1–3 lines) cheaper than preparing context	Prepare less context, not none: a Task with a goal and one acceptance criterion is cheap
AI stuck in a loop on a wrong approach	Change the model or the framing; a loop is a context defect, and fixing the output leaves the defect
Infrastructure config where AI hallucinates	Give the agent the schema or the vendor page; hallucination on config is a missing-context symptom
Time-critical hotfix	Escalate the model, not the process. Where the environment itself is unavailable, this is the recognized case above, not a second one
AI got 90% right — easier to fix 3 lines	A second pass on the same Task costs less than the record the bypass requires

Where you do modify directly, the record is required in every case, including the recognized one — otherwise metric 8 loses the population it is computed over (Standard 9.2). Expect the recognized case to be a small share of your Gate Bypass records; a large one is a statement about your environment. See Guide 06, PF-3 for how to read the number.

Common failures:

Shadow coding — writing code and hiding it from traceability. Under 8.6(j) this is now an unrecorded Gate Bypass, not merely a cultural problem
Micromanaging — rewriting >30% of output instead of improving context
Rubber stamping — accepting without verification

Pillar 3: Enforcement over Ceremony

Quality is enforced through automated gates, not meetings.

AI agents don’t attend meetings, feel accountability, or learn from retrospectives. The only reliable quality mechanism is automated enforcement.

Purpose	Mechanism
Decide what to build	Ceremony
Verify code quality	Gate
Review with stakeholder	Ceremony
Verify requirement met	Gate

Pillar 4: Knowledge Persistence

What is not documented does not exist for AI.

Code documentation is context, not afterthought. In AI-native development, code documentation serves a dual purpose: it helps human Supervisors understand the system AND reduces the context volume AI needs per Task. A well-documented module (docstring explaining purpose, public API contracts, architectural boundaries) means the Supervisor doesn’t need to re-explain these things in every Task goal. AI reads the docs, understands the module’s role, and produces code that fits.

Undocumented code forces the Supervisor to compensate: longer Task goals, more explicit constraints, more scope boundaries. This is expensive context that should live in the code itself. Documentation that says “handles OAuth flow for Google and GitHub, stores tokens encrypted in session table, refreshes automatically” saves 5 lines of Task context on every auth-related task.

Rule 9.11 (Code Documentation as Context) makes this a SHALL requirement: code documentation sufficient for AI to understand module purpose, API contracts, and boundaries without reading the full implementation.

What to capture: decisions (with rationale), patterns, gotchas, dead ends (highest reuse value), observations.

Knowledge delivery to AI: static context files, search APIs, MCP integrations, or RAG. Choose deliberately.

Knowledge lifecycle: current → needs_review (flagged as potentially stale) → deprecated. Stale entries actively harm output quality — they give AI incorrect context.

Pillar 5: Interaction Patterns

AI supervision is a dialogue, not a one-shot command.

Pattern	When to Use
Plan-then-Execute	Complex tasks: ask AI for plan → review → approve → execute
Iterative Refinement	Most tasks: generate → review → course correct → improve
Example-Driven	UI/patterns: “do it like this but with X change”
Negative Example	Known pitfalls: “don’t do X because Y”
Checkpoint-and-Verify	Multi-step: AI does step 1 → verify → step 2
Constraint Fence	Scope control: “change ONLY files X, Y. Do NOT touch A, B”
Rollback-and-Retry	Wrong direction: git rollback, restart with different context
Exploration	Unknown territory: investigate before committing to approach

Context Window Management

AI context degrades as conversation grows (saturation)
Progressive disclosure: provide information as needed, not all at once
Strategic checkpoints clear context and restart fresh
For large codebases: targeted file reads over bulk dumps
Handoffs serialize essential context for new sessions
If AI starts confusing things, it’s not the model — the context is full

Hallucination Management

Common types: non-existent APIs/methods/CLI flags, non-existent files, correct-looking code with subtle edge case bugs, confident but wrong assertions.

Detection heuristics:

Excessive confidence in novel solutions (red flag)
“Suspiciously perfect” code handling every edge case
References to paths/APIs you don’t recognize
Always run the code — don’t trust AI’s claim about what it does

Pillar 6: Empirical Calibration

Every rule and target should be calibrated to your data.

SENAR provides formulas, not targets. Organizations establish baselines by measuring for 3+ Increments, then set targets based on their own reality.

Common failures:

Cargo culting — adopting another org’s targets
Premature optimization — aggressive targets before understanding baselines
Metric fixation — optimizing for metric rather than outcome