Skip to content

🤖 Add system-boundary interviews to the Architect - #819

Merged
taras merged 1 commit into
mainfrom
codex/architect-system-boundary-interview
Sep 14, 2026
Merged

taras merged 1 commit into
mainfrom
codex/architect-system-boundary-interview

Conversation

@taras

@taras taras commented Sep 14, 2026

Copy link
Copy Markdown
Owner

Why

The Architect's main interview handles one unresolved decision well, but it did
not say when a decision should expand into a member-by-member review of an
entire system boundary. The issue #806 design exposed the gap: understanding
ExecutionEnvironment required first explaining the feature each member
enabled, then reconciling its name, type, optionality and JSDoc with that role.

This change makes that deeper interview a permanent, explicitly routed part of
the Architect role.

What changes

Before:

  • The main interview moved from assessment directly to a proposed interface.
  • The understanding interview responded to confusion, but did not escalate when
    the interface itself was unclear.
  • No procedure required the Architect to trace and review every member of a
    system boundary.

After:

  • The main interview's Assessment step explicitly triggers a system-boundary
    interview when the Product Owner requests one or the decision changes a
    multi-member system boundary.
  • The trigger covers ownership, reachability, lifetime, absence, mixed
    responsibilities, neighboring-member coherence and boundary-level confusion.
  • The interview traces construction and consumption before reviewing one member
    at a time through Feature, Example, Current, Contract, Assessment, Proposed and
    Feedback.
  • The existing understanding interview remains the recovery path when an
    explanation is unclear.
  • Local helpers, test/generated shapes, mechanical renames and isolated
    conforming changes remain outside the deeper process.

How it works

main interview Assessment
  → boundary trigger and member inventory
  → one member at a time: feature → example → contract → exact proposal
  → complete-boundary reconciliation
  → resume the main interview

Review guide

Start with: .agents/architect.md, under “Route system boundaries to a
dedicated interview.”

Then review:

  1. The trigger cases and exclusions.
  2. Preparation from real construction and consumers rather than existing names.
  3. The member-review order, which establishes system meaning before wording.
  4. The final reconciliation and prescriptive handoff.

Look carefully at:

  • The new process reuses the existing understanding interview instead of
    introducing a competing response to Product Owner confusion.

What must stay true

  • The Product Owner still makes material decisions — the Architect prepares
    and recommends the exact proposal, then asks one focused question.
  • The ordinary interview remains the default — the deeper interview applies
    only when a listed boundary trigger is present.
  • Implementation details stay delegated — local helpers and mechanical
    changes are explicitly excluded.
  • Adjacent debt does not silently expand the feature — the boundary pass
    separates required changes from follow-up Stories.

How to verify it

  • deno task validate:docs confirms the repository's component-documentation
    contract remains complete.
  • git diff --check confirms the role change has no whitespace errors.
  • Reading the routing section followed by the interview shows a complete path
    from the main Assessment step into and back out of the specialized process.

Scope

Included

  • The trigger from the Architect's main interview.
  • The system-boundary preparation, member review and completion process.
  • Explicit exclusions that prevent the process from absorbing ordinary
    implementation work.

Intentionally unchanged

  • The existing five-part main and understanding interviews.
  • Product-interface, architecture and product-verification rulebooks.
  • Planner, Implementor and Reviewer responsibilities.
  • Product or runtime behavior.

New abstractions

  • The system-boundary interview exists because a multi-member boundary must
    be understood as a coherent system contract before its individual names and
    documentation can be approved.

  • Each new abstraction has multiple concrete uses or a clear justification.

  • No speculative functionality is included.

Risks and limitations

  • A broad trigger could turn local design into a long interview. The explicit
    exclusions keep local helpers, generated shapes, mechanical renames and
    isolated conforming changes on the ordinary path.

Scope confirmation

  • Every changed file supports the purpose described above.
  • Unrelated cleanup and formatting changes are excluded.
  • Generated or mechanical changes are clearly identified.
  • The description matches the final diff and test results.

@github-actions

Copy link
Copy Markdown

PR #819: 🤖 Add system-boundary interviews to the Architect

1 files, +76 / -0

Scope

✅ PR scope looks good.

Structural

✅ No structural bloat detected.

Slop

✅ Slop indicators look low.

Static Analysis

✅ Oxlint found no issues.

Correctness

No extraneous code patterns detected.

@taras
taras merged commit 142b29a into main Sep 14, 2026
37 checks passed
@taras
taras deleted the codex/architect-system-boundary-interview branch September 14, 2026 03:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant