What belongs in the first release of an internal tool?

The short answer

The first release of an internal tool should complete one real job for a named group of users. Include the required records, access rules, failure handling and an agreed way to operate the pilot. Write down what the release excludes so its boundaries can be reviewed.

Start with the workflow the team needs to complete now. Cost and timing depend on that workflow, data quality and agreed scope.

Name the job and follow it through to completion

Write the job in language its users recognise. “Coordinators record a repair request, assign an owner and track it until closure” has a clear start and finish. Ask the current users to walk through that journey and show where the work is recorded today.

Several steps can belong to one job. Split unrelated jobs, such as payroll and repair tracking, into separate scope decisions.

Separate observed problems from proposed features. A duplicate entry the team can show is evidence; a preference for a mobile app needs investigation.

The custom software versus spreadsheets guide helps with the earlier decision about whether a custom tool is warranted.

Choose the records and their lifecycle

List the fields needed to complete the job. For a repair request, these might be location, issue, owner and status. Give each field a purpose and define who maintains it. Add other fields only when the workflow requires them.

Specify the states and allowed transitions. Can a closed request reopen? Does reassignment change who can edit it? What happens to an incomplete request? These questions often reveal work that a screen list misses.

Define history and correction needs. If the team must explain who changed a status, include that evidence in acceptance criteria. Decide how incorrect entries are corrected.

Include the access rules the workflow requires

Define allowed actions and record boundaries for the first users. NIST's least-privilege definition limits permissions to what assigned tasks require. A coordinator might edit assigned requests; a supervisor might reassign requests within the agreed group.

OWASP recommends denying access by default and validating permissions on every request. Its 2025 Top 10 lists Broken Access Control as A01. Give developers explicit allowed and refused cases, including attempts to access another user's record through a direct request. This is part of release acceptance, rather than a reason to build every future role now.

Write observable acceptance criteria

Specify what a reviewer should be able to demonstrate. For example:

• An authorised coordinator can create a request and find it again.
• The assigned owner can update its status.
• A status history identifies the change and its time.
• Invalid fields receive an understandable explanation.
• A failed save does not display a success confirmation.
• A user outside the permitted group cannot read or edit the request.

Use fictional records and separate accounts for different roles. An administrator-only demonstration does not establish staff boundaries.

Include basic usability in acceptance. W3C's forms guidance covers labels, instructions and understandable validation feedback. Its focus-visible guidance explains the need for a visible indicator during keyboard navigation. Staff may use keyboards, zoom or assistive technology during ordinary work.

A hypothetical facilities request board

A fictional facilities team tracks repairs in a shared spreadsheet. Coordinators need to assign work and see outstanding requests. This is an illustration, not a Medivh Code client or a claim of savings.

If a later release connects email or another system, the automation choice guide helps assess that additional workflow. Each integration needs its own delivery and error behaviour.

Define failed saves and competing edits

Describe what users see when a connection drops, a session expires or another person changes the same record. For shared records, a useful acceptance scenario is that a stale edit is refused with an explanation, while the user's proposed changes remain available for review.

The development team must implement the check atomically at the appropriate data boundary. MDN describes conditional HTTP requests using If-Match as one way to prevent an update from overwriting a change made since the record was fetched. The mechanism depends on the stack; the business requirement is to handle that conflict deliberately.

Ask how a failed save is retried safely and how staff establish whether it succeeded.

Agree pilot ownership and rollback

Name the person who manages accounts, reviews pilot issues and decides whether the release is accepted. Document where data is held and who can export or restore it. The secure handover checklist supports that operating agreement.

Choose one authoritative place for pilot records. For the fictional building, the tool could become authoritative at a documented cutover time, with the old spreadsheet retained as a read-only reference. Avoid two freely editable versions with no reconciliation rule.

Before switching, define rollback: who makes the decision, how new requests and updates are preserved, and how staff resume work. A retained spreadsheet is not automatically a current backup of the tool. Demonstrations and training should use synthetic records; any use of real data needs a separately approved handling process.

First-release checklist

• One complete job, its first users and its current workaround are described.
• Required fields, states and allowed transitions are defined.
• Permissions include actions and record boundaries.
• Exclusions include later accounts, reports and integrations.
• Failed saves, competing edits and session expiry have acceptance cases.
• Fictional records and lower-permission accounts are used for testing.
• Labels, errors and keyboard focus are reviewed.
• The pilot has an owner and an authoritative record system.
• Account changes, data recovery and rollback have named responsibilities.
• Acceptance is based on the agreed workflow and evidence.