szpak
Back to tutorials

The Review Comment That Became A Rule

A practical tutorial about turning repeated architecture review comments into deterministic checks, pre-edit questions, recipes, and human decision points.

By the third review, Peter stopped pretending the problem was the pull request.

The assistant had crossed a boundary, the map had shown the import edge, and the team agreed that reports should not know customer internals. That was progress, but Peter had the uncomfortable feeling that they were still doing architecture too late. The same lesson appeared after the work was done, wrapped in another review comment.

This time he did not want to write a better comment. He wanted the comment to stop coming back.

Act I. The Same Sentence Again

The sentence was simple:

This should go through the application service.

Every architect has a sentence like this. It appears in different projects with different names, but the shape is the same. Someone reached around the intended path because the intended path was not obvious, not convenient, or not written down where the work started.

At Ledger House, the sentence had become part of review culture. When a report needed customer data, Peter reminded the team about the customer public query. When a UI component talked too directly to data access, he reminded them about the application service. When audit data appeared as a helper, he reminded them that audit was a module, not a drawer of useful functions.

None of these comments were wrong. They were just late.

The assistant made this more visible because it had no patience for folklore. It did not remember the previous reviews. It did not feel the team’s hesitation around an internal folder. It followed visible structure, and if the visible structure was incomplete, it guessed.

Peter needed a better question than “how do I explain this again?” He needed to ask: what kind of rule is this comment trying to become?

Act II. Classify The Comment

Peter took the sentence and put it on a whiteboard:

This should go through the application service.

Then he refused to turn it into a tool rule immediately. That is a useful discipline. Many architecture comments sound like checks, but only part of them can be checked safely. The rest may be a missing seam, a recipe problem, or a human decision.

So Peter classified the comment.

  • Is it an ownership rule?
  • Is it a dependency rule?
  • Is it a recipe problem?
  • Is it a missing public seam?
  • Is it a human decision that cannot be automated yet?

For the CSV export, the answer was not one thing. Reports owned the export orchestration, so there was an ownership rule. Reports could call customers only through a public seam, so there was a dependency rule. The assistant had created files in an improvised shape, so there was probably a recipe problem. The public customer risk query was unclear, so there was also a pre-edit question.

That is why the original review comment kept coming back. It was carrying four different expectations in one sentence.

Deterministic Contract Plus Human Judgment

Some parts of architecture can be checked from code structure. Some cannot. The mistake is pretending that everything belongs on one side.

Peter split the CSV problem into two groups.

The deterministic part was the boundary:

reports cannot import customers/internal/**

The human part was the missing design choice:

which customer query is the public seam for risk data?

The first one can become a check. The second one should become a pre-edit question. If the assistant cannot answer it from the route, it should stop and ask before inventing a path.

This split is important. A check is good when the repository has enough evidence to prove the rule. A question is better when the repository needs human judgment. A recipe is better when the correct shape exists, but the wrong shape is easier to create. A rule document is better when the expectation must be read before work starts.

Peter did not need one perfect mechanism. He needed the right mechanism for each part of the comment.

Turning One Comment Into Four Things

The repeated review comment became this:

Review comment:
- This should go through the application service.

Boundary check:
- reports cannot import customers/internal/**
- ui cannot import customers/internal/**

Pre-edit question:
- which customer public query provides risk data?

Recipe need:
- report exports should start from reports/application and reports/ui slots.

Human decision:
- if no public risk query exists, should customers expose one, or should the
  feature be owned by another module?

This is less elegant than the original sentence. It is also much more useful.

The assistant can run a boundary check. It can follow a recipe. It can report a missing public seam. It can ask Peter for the human decision before touching the wrong files.

The old comment was a correction. The new contract is a steering mechanism.

What Goes Into enclosure

Peter placed each part where it belonged.

The boundary went into enclosure.yaml, because it was structural and deterministic:

architecture:
  root: src
  boundaries:
    rules:
      - {
          source: "reports/**",
          disallow: ["customers/internal/**"],
          allow: ["customers/public/**"],
        }
      - {
          source: "reports/ui/**",
          disallow: ["customers/**", "audit/**"],
          allow: ["reports/application/**"],
        }

The pre-edit question went into the reports rule, because it depends on the kind of work:

Before changing report exports:
- Name the owner.
- Name the public customer seam.
- Name the public audit seam.
- Stop if either seam is missing.

The recipe note stayed in the plan for the next improvement:

Report export recipe:
- reports/application/<export-name>
- reports/ui/<export-name>
- reports/tests/<export-name>

This is the practical shape of enclosure: checks where the repository can prove something, rules where the assistant must read something, recipes where the team wants a repeated shape, and human gates where the system still needs a decision.

The Route Receipt Changes

Now the assistant cannot simply say that it read the reports rule. It has to show what the rule means for this change:

Route read:
- Files: .enclosure/rules/INDEX.md, .enclosure/rules/shared/INDEX.md,
  .enclosure/rules/local/reports.md
- Reason: customer risk export changes report orchestration.
- Owner: reports owns export orchestration.
- Public customer seam: customers/public/customer-risk-query.
- Public audit seam: audit/public/audit-query.
- Forbidden dependencies:
  - reports -> customers/internal/**
  - reports/ui -> customers/**
- Checks to run:
  - boundary check
  - report export tests
- Stop condition:
  - public risk query is missing or ambiguous

This receipt is not paperwork. It is the assistant proving that it understood the comment before it turned into code.

If the assistant writes:

Public customer seam: not found

then the next action is not implementation. The next action is a question. Peter can decide whether to add the seam, reuse an existing one, or move ownership of the feature.

That is the difference between cooperation and guessing.

The Important Failure Mode

There is one trap here. Peter does not want to turn every preference into a hard check. That is how teams create brittle rule systems that everyone learns to fight.

If the rule is really a taste preference, do not pretend it is a boundary. If the rule depends on business context, do not hide the decision inside a glob. If the rule cannot be checked reliably, make it a pre-edit question instead.

The goal is not to make the repository say “no” to everything. The goal is to make the repository say the right thing at the right time:

  • “this import is forbidden”;
  • “this seam is missing”;
  • “this shape has a recipe”;
  • “this decision needs a human”.

That is much more useful than a long list of rules which are half true and mostly ignored.

Exercise

Choose one review comment you have written at least three times. It should be small and concrete, not a slogan.

Write it down:

Review comment:

Now split it:

Ownership rule:
Dependency rule:
Recipe problem:
Missing public seam:
Human decision:
Check command:
Stop condition:

Do not force every line to have an answer. Empty lines are useful because they show what kind of rule you actually have. If only the dependency rule is clear, start there. If the real problem is a missing public seam, write the question before inventing a check. If the same folder structure is created again and again, make a recipe.

Then ask an assistant to report this split before editing a related task. If it cannot classify the rule, the repository has not explained the work clearly enough yet.

Summary

A repeated review comment is a signal. It usually means the architecture exists, but it appears too late. The useful move is not to write the same comment with more frustration. The useful move is to classify it.

Some parts become deterministic checks. Some become pre-edit questions. Some become recipes. Some remain human decisions. enclosure gives those pieces places to live, so the assistant can cooperate with the architecture before the next pull request is already wrong.

In the next tutorial, Peter will deal with the recipe problem. If the good path is harder to start than the shortcut, the assistant will keep choosing the shortcut.