Skip to content

Create the fix entry from a resolved range #267

Description

@sameera

As a developer who has landed a small fix, I want to record why it mattered in one command, so that the reason reaches the concept store at a cost the change justifies.

Acceptance Criteria

  • Given a resolved reference and range, when the developer completes /nxs.fix <ref>, then the command creates .nexus/tmp/fix-<n>/ holding exactly epic.md and close-record.md, and reports both paths and that /nxs.distill will drain them.
  • Given the command has completed, when GitHub and the repository are inspected, then no issue, comment, branch, or pull request was created and nothing was committed.
  • Given the created epic.md, when its frontmatter is read, then it carries title, link holding the reference the developer gave in canonical provenance form, slug: fix-<n>, and entry_kind: fix, and the file has no body.
  • Given the created close-record.md, when it is read, then it carries one range entry of repo, base, and head, an analyze: value of n/a — fix entry (no acceptance criteria), a ## Key Decisions section holding the reason the developer gave, and a ## Deviation Rationale section stating that a fix entry has no decision record to deviate from.
  • Given the created close-record.md, when it is read, then it has no record key, no record_hash key, no ## Deferred Scope section, and no ## Process Lesson section.
  • Given a resolved range, when the command prompts the developer, then it asks for exactly two things: the reason the change mattered, which is required, and the feature the fix belongs to, which the developer may leave empty.
  • Given a resolved range, when the command builds that prompt, then it has already derived the description of what changed from the diff of the range, and it does not ask the developer to describe the change.
  • Given the developer left the feature empty, when epic.md is written, then the feature key is omitted rather than written with a value the command guessed.
  • Given a diff whose changed paths map to no page in the store, when the command prepares the prompt, then it prints a warning naming how many behaviors it found with no existing page, and it still writes the entry. The check is best-effort, so failing to warn is not a defect.
  • Given the command has completed, when the run is inspected, then no approval checkpoint was presented and no analyze-receipt.md was written.

Notes

The prompt for the reason is the lane's forcing function, and it is the only required human input. #266's range prompt is separate and conditional: it happens before this one, and only when the range cannot be resolved from the reference and no --range argument was given.

The warning in the second-to-last criterion is advisory and fails soft. It cannot be load-bearing, because this command writes no pages and can only guess at what the drain will later synthesize. The load-bearing gate is #269.

There is no approval checkpoint because the command writes nothing durable and nothing to GitHub. A second gate over a scratch directory would be ceremony.

The file names epic.md and close-record.md are deliberate. They assert nothing about an epic existing or about anything having been closed. They keep the drain's discovery change to one line instead of a parallel code path, and entry_kind: fix is the field that carries the truth.

story_type: user · size: M

Metadata

Metadata

Assignees

No one assigned

    Labels

    pipelineOrchestration of the Nexus stages and human-decision gatesstoryUser story (created by nxs-gh-create-story)

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions