Internal Tool Requirements Template: Specify the Work, Not Just the Screen

# Internal tool requirements template

Complete this with the people who perform and receive the work. Attach sanitized representative cases. Never paste live secrets, tokens, personal data, customer confidential data, or exploitable architecture details into a shared brief.

## 1. Job and outcome

- Tool or working name:
- Accountable service owner:
- Business decision owner:
- Problem in one sentence:
- Trigger that creates exactly one item:
- Observable finish states:
- Users and roles:
- Service expectation or deadline:
- Current manual process and fallback:
- Measures before change: volume, active time, elapsed time, corrections, exceptions, missed work, harmful outcomes:

## 2. Scope

- In scope for version one:
- Explicitly out of scope:
- Users, records, locations, and volume limits:
- Actions allowed automatically:
- Actions produced only as drafts:
- Actions requiring permanent human approval:
- Stop conditions:

## 3. Inputs and data

For each input record the field, source of truth, owner, required or optional status, validation, freshness, sensitivity, purpose, retention, deletion, masking, and missing-data path.

| Input | Source | Owner | Validation and freshness | Sensitivity and purpose | Missing-data path |
| --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |

## 4. Workflow behavior

- Normal states and transitions:
- Deterministic rules and calculations:
- Bounded AI judgment, allowed outputs, examples, confidence or abstention behavior:
- Notifications and their owners:
- Duplicate identity and business key:
- Exactly what happens after approval, rejection, expiry, withdrawal, or cancellation:

## 5. Exceptions and failures

Describe at least three real exceptions. Include missing input, invalid input, duplicate request, stale state, denied authority, dependency unavailable, timeout after possible effect, partial effect, and notification failure where applicable.

| Condition | Detection | State and owner | Allowed action | Evidence | Return or close path |
| --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |

## 6. Identity, authority, and secrets

- Human authentication method:
- Service identities and environments:
- Default-deny authorization model:
- Record, field, function, and action permissions by role:
- Approval authority, delegation, evidence, expiry, and version binding:
- Secret storage, access, rotation, revocation, and log exclusion:
- Rate, value, batch, and scope limits:

## 7. Evidence and monitoring

- Request and input version retained:
- Decision or model version retained:
- Approval or rejection actor, time, evidence, and scope retained:
- Attempted effect, destination response, confirmed postcondition, correction, and final outcome retained:
- Business outcome metrics:
- Technical and dependency health metrics:
- Alert condition, recipient, immediate action, severity, and duplicate suppression:
- Exception queue owner, service clock, and escalation:

## 8. Acceptance cases

Attach at least two normal cases, two boundary cases, three exceptions, one duplicate, one denied action, one stale-input case, one timeout-after-possible-effect case, and one recovery case. For each, specify inputs, expected state path, permitted effects, evidence, and owner.

## 9. Rollout and recovery

- Historical replay plan:
- Observation or draft-mode plan:
- First live users, records, actions, and volume:
- Manual fallback and how it is activated:
- Maximum acceptable outage or backlog:
- Effect reconciliation method:
- Rollback or compensation path:
- User correction and incident reporting path:
- Release decision owner and evidence:

## 10. Change and retirement

- Dependency inventory and notice owners:
- Policy and process change owner:
- Versioning and regression suite:
- Change reviewer, approver, release, verification, and communication path:
- Review cadence:
- Value and ownership review date:
- Retirement triggers:
- Export, evidence retention, trigger shutdown, credential revocation, user notice, and archive steps:

## Decision record

- Chosen delivery model:
- Alternatives considered:
- Assumptions that must remain true:
- Highest-consequence failure and its control:
- Named reviewers:
- Decision date:
- Next review date: