p4r1h/naksha/spatial-feedback-loop

Reviewing spatial work with an agent

Prose is a poor encoding for geometry. "The door should be a bit further left, past where the storage ends" is several sentences that still do not say where, and the agent cannot see what you are looking at.

This describes a channel that removes the ambiguity, and the prompting habits that go with it.

The core mechanism

Let the running application write to a file the agent reads.

  browser                dev server              agent
  -------                ----------              -----
  click in the      ->   POST /__comments   ->   comments.json
  scene, type a          writes to disk          read directly,
  note                                           acted on

About thirty lines of dev-server middleware. In Vite:

function commentApi() {
  const file = path.resolve(process.cwd(), 'comments.json');
  return {
    name: 'comment-api',
    configureServer(server) {
      server.middlewares.use('/__comments', (req, res) => {
        res.setHeader('Content-Type', 'application/json');
        if (req.method === 'GET') {
          res.end(fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '[]');
          return;
        }
        if (req.method === 'POST') {
          let body = '';
          req.on('data', (c) => { body += c; });
          req.on('end', () => {
            try {
              JSON.parse(body);              // reject malformed writes
              fs.writeFileSync(file, body, 'utf8');
              res.end('{"ok":true}');
            } catch {
              res.statusCode = 400;
              res.end('{"ok":false}');
            }
          });
          return;
        }
        res.statusCode = 405;
        res.end('{"ok":false}');
      });
    }
  };
}

Equivalents exist for any dev server: a Next.js route handler, an Express middleware, a Python dev server handler. The requirement is only that the page can persist to somewhere the agent has file access.

What a pin should carry

Position alone is not enough. Capture whatever context the application already knows, because the agent cannot infer it from a coordinate:

{
  "id": "cmt6yve8c",
  "at": "2026-08-24T08:21:06.636Z",
  "floor": "F",
  "x": 534, "y": 184, "z": 0,
  "room": "outside any room",
  "text": "entrance is here, aligned with the lift, put door and wall here",
  "done": true
}

floor and room came from the app's own hit-testing. That is three facts the author did not have to type and could not have typed accurately.

A done flag matters more than it looks: it lets notes stay in the file as a record while dropping out of the active list, so the agent sees what is outstanding rather than re-reading forty resolved items.

Closing the loop

Point the agent at the file. Either mention it when you have left notes, or run a monitor that watches for changes and wakes the agent. A monitor makes it feel like review rather than instruction, but it is not required for the mechanism to pay off.

Why this is worth building early

The measurable effect: one misplaced door in a 3D model took four written attempts and one pin. The sentences kept saying "here". The pin carried coordinates, the storey, and which room the click landed in.

Build it before you need it. The cost is fixed and small; the saving scales with every spatial correction after it, and spatial corrections are most of the work in visual projects.

Images are the same idea

An annotated screenshot is a pin with more bandwidth. A line drawn over a render settled a circulation route in one message after three written attempts. A photograph of a hand sketch settled a kitchen layout that three descriptions had not.

If a correction is about where or what shape, reach for an image before a paragraph.

Prompting

Four patterns, all about information content rather than phrasing.

Describe the symptom, not the remedy

Within a few hours the agent holds more of the codebase than you do. Prescribing an implementation discards that and substitutes a worse guess.

the couches in the living room are facing outwards they should be facing

inwards

Current state, desired state, nothing about how. Corrections written this way land first try. Corrections that name a file and a function usually need a second pass, because the guess about which file was wrong.

Count the facts in your message

The best predictor of a one-shot fix is how many facts the message carries about the object being changed.

the wardrobe in parents bedroom is still horizontally aligned and way too

big, it needs to be vertically aligned along the bathroom wall and as big as

the bathroom wall

Element, location, wrong property, correct property, and a reference to size it against. Five facts, fixed once.

A partition elsewhere took four attempts. The failures said it was cut in the wrong place. The one that worked said which end it should extend past and which element it should stop at. Tone varied across those attempts and made no difference. Information content did.

Ask whether it is correct, separately from asking for it

An agent reports what it did. Whether the result is right is a different question, and asking costs one message.

Are you sure? I see a lot of points where the walls meet dont make clean

corners still

produced the largest structural change in that project. Nothing preceding it had been reported as incomplete, because nothing about it was known to be incomplete.

Apply the same before work as after it. Asking for a scope estimate before authorising a feature - "how much work would that be?" - returns something specific enough to decline with, and declining is usually the right answer.

One change per message

Requests containing five changes reliably produce two good results, two approximate ones, and one silent omission. Sequential single changes are faster in wall-clock terms despite more round trips, and far easier to verify, because a failure is attributable to a specific request.

Let it disagree

When an agent argues against a request, that is information. Twice in one project a proposed feature was argued down correctly: once an element that would have been invisible from the viewing angle, once an automation that measured worse than doing it by hand. Both would have been built if the agent had simply complied.

Verification the agent can do alone

Pins are for things you noticed. The agent should be able to check its own work without you looking, which requires two things.

A way to render a specific view from the command line. URL parameters that set the camera, the visible layer and any mode, so a headless screenshot can reproduce an exact view. Without this the agent is guessing what changed.

Checks that run on the data rather than the output. A picture that looks right is not evidence. Scripts that validate the underlying model catch a class of error no screenshot will.

Together these mean the pin channel is reserved for judgement - things that are wrong rather than broken - which is what a human is actually needed for.

Checklist

• [ ] The app can write to a file the agent reads
• [ ] Pins capture app-known context, not just coordinates
• [ ] Resolved notes are marked, not deleted
• [ ] The agent is pointed at the file, or a monitor watches it
• [ ] A view can be reproduced from the command line for screenshots
• [ ] Data-level checks exist so the agent can self-verify
• [ ] Corrections describe the symptom, not the fix
• [ ] One change per message