# Developer assessment brief

Updated: 28 September 2026

Use this editable template to agree a small paid work sample and record the evidence behind a hiring decision. It is suitable for different languages and roles. Complete the blanks before assigning work; prepare the exercise repository separately. Use fictional data and test credentials throughout.

## 1. Role and decision

- Role being considered: [role]
- Responsibilities during the first month: [up to three concrete responsibilities]
- Experience this exercise should demonstrate: [specific capability]
- Capabilities it will not establish: [for example production incident handling or load behavior]
- Candidate identifier: [reference]
- Reviewer and decision owner: [names or roles]
- Review date: [date and time zone]

## 2. Supplied environment and access

- Repository/archive and baseline commit: [location and revision]
- Runtime, framework and package-manager versions: [versions]
- Database and required local services: [versions and setup]
- Setup instructions and baseline check command: [reference]
- Known baseline failures or limitations: [list, or none after buyer verification]
- Fictional accounts, roles and records: [fixture inventory]
- Documentation and files the candidate may use: [references]
- Documentation/assistant/tool policy: [state the same rules for all candidates]
- Access scope and expiry: [disposable test environment only]
- Contact for a broken environment or ambiguous requirement: [channel and owner]
- Submission location and expected access-removal/deletion steps: [instructions]

Do not include production credentials, customer records or confidential third-party code. If the supplied baseline cannot run, pause the exercise and resolve the setup issue. Agree additional paid time before asking the candidate to investigate an environment problem outside the brief.

## 3. Payment and time limit

- Fee and currency: [agreed amount]
- Included work: [reading, implementation, checks, notes and review round]
- Maximum work time: [duration]
- Review round and its maximum paid time: [duration and format]
- Submission deadline and time zone: [deadline, distinct from work time]
- Payment date or trigger: [clear terms]
- Payment for the agreed work is due regardless of the hiring decision: [confirm]
- Permitted use of the submission: [assessment only, or separately agreed use]
- Change procedure: [who agrees any extra paid scope before it begins]

At the time limit, submit the current work and identify what remains unfinished. Do not extend the assignment into unpaid work.

## 4. Task and expected outputs

**Current behavior:** [one reproducible problem]

**Required behavior:** [observable outcome and behavior that must remain intact]

**Supplied inputs:** [records, requests, files or other examples]

**Included changes:** [bounded scope]

**Excluded changes:** [features, upgrades, deployment, redesign or other work outside scope]

**Expected outputs:**

- A focused patch or agreed equivalent artifact.
- Relevant regression checks or an agreed verification method.
- A short explanation of the cause and change location.
- Commands or procedures actually used, with results and environment.
- Unrun checks, assumptions, limitations and any release/handover notes.

## 5. Acceptance observations

Share expected behavior before the exercise. Prepare the supporting fixtures and make all promised inputs available. Do not add undisclosed requirements after reviewing a submission.

| Case/input | Expected behavior | Observed behavior | Evidence reference | Status |
| --- | --- | --- | --- | --- |
| [ordinary allowed case] | [expected output] | [reviewer records] | [test, command or artifact] | [demonstrated / partial / not observed / critical issue] |
| [denied or invalid case] | [expected outcome] | [reviewer records] | [reference] | [status] |
| [missing record or external failure] | [expected outcome] | [reviewer records] | [reference] | [status] |
| [existing behavior to preserve] | [expected outcome] | [reviewer records] | [reference] | [status] |
| [side effect that must not occur] | [expected outcome] | [reviewer records] | [reference] | [status] |

Distinguish checks that ran from checks that are merely proposed. Record an environment blocker as a blocker, rather than silently treating it as a passed or failed capability test.

## 6. Review worksheet

Use observations, not a total score that could hide a critical unresolved requirement.

| Area | Evidence to inspect | Observation and remaining gap |
| --- | --- | --- |
| Understanding | Traces the relevant behavior and identifies existing conventions | [notes] |
| Correctness | Meets the agreed allowed, denied and failure cases | [notes] |
| Change quality | Focused, readable work with justified dependencies and scope | [notes] |
| Verification | Reproducible checks and accurate reporting of their limits | [notes] |
| Delivery/handover | Applicable release steps, limitations and clear reviewer guidance | [notes] |

- Critical conditions for this particular task: [define before work begins]
- Candidate clarification or correction: [record fairly]
- Decision: [proceed / bounded paid follow-up / decline for this role]
- Evidence supporting the decision: [specific references]
- Capability still unobserved: [gap]
- Initial responsibility and review support if proceeding: [scope]
- Any paid follow-up: [one objective, fee, time cap and decision it will resolve]
- Written feedback and payment completion: [owner/date]

## Fictional filled example: PHP maintenance role

This example supplies a design for an exercise, not an application or completed candidate result. All accounts and reports are fictional.

- **Role:** maintain an existing PHP application's request and data-access behavior, with code review before release.
- **Environment to supply:** PHP 8.3, Laravel 12, locked dependencies, a disposable SQLite database, setup instructions and a verified baseline test command.
- **Problem:** a manager can change a report identifier and retrieve another workspace's draft-report preview.
- **Task:** repair the JSON preview endpoint's access boundary, preserve its allowed response, and add regression checks and a short README.
- **Inputs:** workspaces A and B, a manager of A, a viewer of A, a revoked membership, a manager belonging to both workspaces, and draft reports owned by each workspace. Document the preview response fields in the supplied fixture.
- **Time:** two paid hours for investigation, the patch, checks and notes, plus up to 20 paid minutes for one written review round. Pause for a broken supplied environment.
- **Payment:** an illustrative fixed fee of USD 240 covering that scope, payable within five business days of submission regardless of hiring outcome. This fictional amount is not a market-rate recommendation.
- **Tools:** documentation and assistants permitted; the candidate explains and verifies the submitted work. Share no real customer data or credentials with tools.
- **Use:** assessment only. No production access or deployment.
- **Excluded:** new authentication, schema changes, feature additions, framework upgrades and production concurrency certification.

### Expected observations for the fictional fixture

| Case | Expected behavior |
| --- | --- |
| Active manager, own workspace and report | 200 with the documented preview fields |
| Manager selects an authorized workspace but supplies another workspace's report ID | 404 with no report data |
| Manager lacks active membership in the requested workspace | 403 with no draft-report data |
| Viewer or revoked membership | 403 with no draft-report data |
| Unauthenticated JSON request | 401 |
| Otherwise authorized caller with identifiers that are not positive integers | 422 |
| Authorized manager, missing report | 404 |
| Any preview request | No business records changed |

The dual-workspace manager fixture helps distinguish permission to use a workspace from selecting a record in that workspace. Agree these observations before assignment; do not infer test results from this example.

Critical issues are cross-workspace data disclosure, weakening an existing permission check, destructive changes outside scope or knowingly misrepresenting test results. Record the actual evidence before deciding whether the candidate demonstrated readiness for this maintenance role. Leave the reviewer decision blank until the work is assessed.

Related guide: https://nomadicsoft.io/blog/best-php-developers