Sb Gap Analysis

Analyze the distance between the need and what exists

Apply project language style

Before authoring any artifact or user-facing prose, read:

specbind rule read language-style --for consume

Apply returned policy only to natural-language prose. NO_CHANGE RULE_ABSENT means no additional project preference; any ERROR line stops the workflow.

Establish what the repository already provides, name precisely what is missing, and hand the next phase material it can decide from. You inform. You do not decide.

Read the protocol before you start. It owns how evidence is gathered, how gaps are named, and how uncertainty is handled:

specbind protocol read gap-analysis

1. Read

specbind spec status <spec>
specbind artifact list <spec>
specbind steering list

Then:

• the Spec's brief — always
• every steering document the listing named
• the Requirements, when the Spec has them
• the existing research, when one exists
• the contract, and the contracts across a seam this work touches, when boundaries are in scope

An ERROR line from steering list or steering read stops you. An analysis built against a knowingly partial view of the project's constraints is worse than none, because it is persuasive.

Read the project's own preferences through its rule surface:

specbind rule read design-principles --for consume
specbind rule read contract-principles --for consume

The second read is required when boundaries are in scope. NO_CHANGE RULE_ABSENT means no customization; any ERROR line stops the analysis.

Requirements is an input, not a precondition. This skill runs before Requirements exist as readily as after. Discovery deliberately refuses technical evaluation, so running here — right after routing, before the behavior contract is written — is the point where the answer is cheapest to act on. When no Requirements exist yet, read the milestone's complete current scope and work from it together with the brief:

specbind milestone scope

2. Decide whether there is anything to compare

If the affected area has no meaningful existing implementation, say so in a sentence and stop. A greenfield comparison produces an empty document and the impression that something was checked.

3. Investigate

Dispatch fresh readers rather than reading everything yourself. Each starts with no context, so give it a brief that stands alone and a question it can answer. Use the registered specbind-researcher role when available, with ordinary fresh readers as the fallback. Fallback is only for an absent role. A configured role whose model cannot start is a configuration or environment failure, not permission to change models. The independent lines are:

• What exists in the affected area — modules, layout, reusable components
• What constrains it — layering, dependency direction, where tests live, the patterns already in force
• What it must meet — data models, external clients, authentication, and the other integration surfaces
• What an external dependency actually offers, when one is in question

You may investigate outside the repository. Record the sources, and never present an external claim as an observation about this codebase — those are different kinds of statement and the reader has to be able to tell them apart.

Read the code. An analysis built on a plausible but wrong picture of the system is the expensive failure here.

4. Route what you found

Anything that changes what is being asked for goes back to the user before it goes anywhere else.

That second row is the one to hold. "The current code makes this awkward" is a design constraint, and letting it reach Requirements turns accidental structure into an obligation the project has promised.

Only revise the brief once the user has accepted the change. The brief holds the requester's own words. Rewriting them on the strength of a technical finding is exactly what this routing exists to prevent.

Before the first managed Markdown write in this run — a user-approved Brief revision here or a Research artifact below — read the authoring protocol once:

specbind protocol read okf-authoring

5. Decide whether to write the research artifact

Research is optional and its absence is normal. Write it when the finding outlives the analysis:

• substantial investigation that a later session would otherwise repeat
• conclusions the design phase will need and cannot reconstruct cheaply
• the user asked for it

Do not write it when the Design will absorb the conclusions in full. Routine analysis needs no separate document.

Say which you chose, and why. A silent omission is indistinguishable from forgetting.

If you write it:

specbind template read spec research

If this is the first managed Markdown write in the run, read okf-authoring as directed above before materializing the artifact. Do not read it a second time when a Brief revision already required it.

Follow every scoped instruction the template returns. Follow every create output=<name> instruction once to produce its named output. An output may be a short string or a Markdown fragment. Replace every reference to that name with the same produced output, omit create comments from the materialized artifact, copy every maintain and consume comment unchanged, and write it at the Spec's research path.

Do not persist the rendered heading as an empty placeholder. A live Research artifact requires substantive findings; when none are useful, keep it absent.

Replace an existing research document. Do not append to it. Read the current document with artifact read <spec> research --for maintain first and preserve its durable scoped comments. Research states the current view of the investigation; a document that accumulates every superseded finding makes the next reader work out which conclusions still hold. Git holds the earlier drafts.

Mark where each conclusion has to land

Research is deleted at release finalization. A conclusion recorded only here is one the project has decided to forget. Mark each one:

The last row matters as much as the others. Marking everything for promotion buries the conclusions that actually need it.

6. Report

Lead with the answer. In the project's language:

• what exists that this work can build on
• what is missing, what is unknown, and what is constrained — kept distinct, because conflating them hides work
• the realistic options with what each costs. A preference is welcome, visibly as a recommendation with its reasoning; a single option presented as analysis is a decision in disguise
• whether you wrote research, and why
• anything you routed back to the user

Boundaries

• Author Research, with one narrow exception: after the user accepts a request change exposed by the analysis, revise that Spec's Brief to carry the requester's new terms. Requirements, Design, Contract, and tasks.yaml belong to their phases. Write no machine state.
• Inform, do not decide. Gathering the evidence does not make the decision yours.
• Not a gate and not a precondition. Nothing waits on this, and Design proceeds whether or not it ran.
• If the analysis suggests the scope itself was wrong — work in the wrong Spec, a boundary in the wrong place — report it. Discovery owns that change; do not create Roadmap items or Specs here.
• Research binds nothing. Requirements, Design, and Contract remain the authoritative statements, and no later artifact may defer meaning to what you write here.