Form errors: explain, correct, and retry

# Apply the “Form errors: explain, correct, and retry” guide in your agent

## Objective
Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. Link an error summary to the fields, verify keyboard focus, and distinguish server rejection from a network failure. Confirm success only after the server accepts the operation.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Build a validation journey with field messages, server errors, focus, and safe recovery.
- Preserve the correct decisions already in place.

## Guide steps
- 1. 1. Prepare a small, testable form — Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. A red border alone cannot tell someone what to change.
- 2. 2. Explain the field error — Use a native label and suitable input type, with required or other relevant constraints. Explain format requirements before submission. Validate on submission first; if adding blur validation, avoid interrupting an unfinished value on every keystroke.
- 3. 3. Bring errors into reach — After a rejected submission, show a summary above the form with links to the affected fields. Choose and test one focus strategy: focus that summary (programmatically focusable) for several errors, or the first invalid field for a short form. Do not move focus during ordinary typing.
- 4. 4. Handle server rejection and uncertain outcomes — The server must validate independently. Map a field-specific rejection to that field; show a service outage as a form-level message with a retry action. Do not label every field invalid because the network failed. Preserve non-sensitive input and explain any sensitive value that must be entered again.
- 5. 5. Run the recovery scenario — In the test environment, submit an empty form, then a malformed email, then a valid-looking value rejected by the server. Follow summary links using only the keyboard, correct one error, and confirm unrelated input survives. Simulate an outage, restore the service, and complete one successful save.
- 6. Check recovery after a second error — Enter a valid name and an invalid email, submit, then correct only the email. If another field is rejected, its message must identify that field and explain the correction. Follow the error link with the keyboard and verify the valid name remains.

## Acceptance criteria — Evidence to keep
- Field error explains a correction and is associated with the field.
- Keyboard recovery preserves valid values and reaches confirmed success.
- Server rejection, outage, and uncertain save have distinct outcomes.
- Each error-summary link moves keyboard focus to its corresponding field.
- A corrected field loses its obsolete error without clearing other values.
- Pending submission prevents duplicates and exposes a readable status.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Anchor the guide in the project

## Objective
Turn the applied steps into durable repository conventions.

## Checks
- Link each decision made to the guide step that justifies it.
- Add the checklist to the relevant reviews.
- Record out-of-scope cases for the neighboring guides.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:9358dbb7178ef7e213bbe12802826ce097087913faacaac515a1da1168adb3d7

# Diagnose a failed application of the “Form errors: explain, correct, and retry” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. 1. Prepare a small, testable form — Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. A red border alone cannot tell someone what to change.
- 2. 2. Explain the field error — Use a native label and suitable input type, with required or other relevant constraints. Explain format requirements before submission. Validate on submission first; if adding blur validation, avoid interrupting an unfinished value on every keystroke.
- 3. 3. Bring errors into reach — After a rejected submission, show a summary above the form with links to the affected fields. Choose and test one focus strategy: focus that summary (programmatically focusable) for several errors, or the first invalid field for a short form. Do not move focus during ordinary typing.
- 4. 4. Handle server rejection and uncertain outcomes — The server must validate independently. Map a field-specific rejection to that field; show a service outage as a form-level message with a retry action. Do not label every field invalid because the network failed. Preserve non-sensitive input and explain any sensitive value that must be entered again.
- 5. 5. Run the recovery scenario — In the test environment, submit an empty form, then a malformed email, then a valid-looking value rejected by the server. Follow summary links using only the keyboard, correct one error, and confirm unrelated input survives. Simulate an outage, restore the service, and complete one successful save.
- 6. Check recovery after a second error — Enter a valid name and an invalid email, submit, then correct only the email. If another field is rejected, its message must identify that field and explain the correction. Follow the error link with the keyboard and verify the valid name remains.

## Possible causes
- A step was skipped or executed out of order.
- The actual need falls outside the guide scope.
- A checklist criterion was never verified.

## Bounded fixes
- Redo only the diverging step and what depends on it.
- Document the gap if the guide scope does not cover the need.

## Final verification — Evidence to keep
- Field error explains a correction and is associated with the field.
- Keyboard recovery preserves valid values and reaches confirmed success.
- Server rejection, outage, and uncertain save have distinct outcomes.
- Each error-summary link moves keyboard focus to its corresponding field.
- A corrected field loses its obsolete error without clearing other values.
- Pending submission prevents duplicates and exposes a readable status.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Prevent the next drift

## Objective
Turn the first diverging step into an explicit project check.

## Checks
- Add a focused check on the step that diverged.
- Verify the checklist on a second real case.
- Document the scope limit you hit.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:e8f1f0368f042e48c9f6ef3914e7e06a6507df693567bdeabaa8eae0c5d48aad