Ask for a permission when its purpose is clear

# Apply the “Ask for a permission when its purpose is clear” guide in your agent

## Objective
Connect each permission request to a deliberate action and a specific purpose. Explain what will be used before the platform prompt, request only the necessary capability and preserve an alternative after refusal. Permission granted, hardware available and active capture are three different states.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Explain camera, microphone or location access, handle refusal and show when the capability is actually active.
- Preserve the correct decisions already in place.

## Guide steps
- 1. Tie access to a task — For an expense app, scan a receipt should request camera access when chosen, not on the dashboard’s first load. Explain that the camera supplies a receipt image and identify any later upload separately. Avoid requesting camera, microphone and location together for convenience. A permission explanation is not consent for unrelated processing, retention or sharing; those boundaries need their own clear contract.
- 2. Model the actual states — Distinguish not asked, prompt pending, granted, denied, unavailable and active. A permission query may be unsupported or insufficient to predict whether capture will succeed; handle the actual capability call too. Only show Recording when capture has started. A denied prompt or missing device must never leave an active indicator. Stop access when the user stops or leaves the capture task.
- 3. Example: attach a receipt — Offer Take a photo and Choose a file. Explain the camera need, request it after selection, then show the captured preview before a separate submit action. Let users retake or discard the image. After refusal, retain Choose a file and a brief explanation of how to change access in browser settings. Do not repeatedly open prompts or imply the alternative requires granting the permission.
- 4. Handle revocation and failure — If access disappears during use, stop capture and retain only data already accepted under the stated policy. Explain whether the draft image survived. Reopening should reflect actual state, not a cached granted flag. Secure-context, browser and operating-system restrictions vary. Link to supported setup instructions without bypassing security warnings or telling users to broadly disable protections.
- 5. Verify without collecting real private data — Use a fixture image and exercise grant, refusal, no device and revocation. Check that the fallback works and capture stops when requested. Do not upload a real receipt merely to test the flow. This guide covers interaction boundaries, not legal consent or native-device certification. A mocked permission test does not establish behavior on every physical phone.

## Acceptance criteria — Verify in your product
- The request follows an intentional action.
- Only necessary access is requested.
- Granted and active differ.
- Refusal retains a usable alternative.
- Leaving stops capture.
- Upload and retention are explained separately.

## 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:a50fa6cb39067099b9d8fd7de9da764236e171afff64a482e5f02255fd9f94a8

# Diagnose a failed application of the “Ask for a permission when its purpose is clear” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. Tie access to a task — For an expense app, scan a receipt should request camera access when chosen, not on the dashboard’s first load. Explain that the camera supplies a receipt image and identify any later upload separately. Avoid requesting camera, microphone and location together for convenience. A permission explanation is not consent for unrelated processing, retention or sharing; those boundaries need their own clear contract.
- 2. Model the actual states — Distinguish not asked, prompt pending, granted, denied, unavailable and active. A permission query may be unsupported or insufficient to predict whether capture will succeed; handle the actual capability call too. Only show Recording when capture has started. A denied prompt or missing device must never leave an active indicator. Stop access when the user stops or leaves the capture task.
- 3. Example: attach a receipt — Offer Take a photo and Choose a file. Explain the camera need, request it after selection, then show the captured preview before a separate submit action. Let users retake or discard the image. After refusal, retain Choose a file and a brief explanation of how to change access in browser settings. Do not repeatedly open prompts or imply the alternative requires granting the permission.
- 4. Handle revocation and failure — If access disappears during use, stop capture and retain only data already accepted under the stated policy. Explain whether the draft image survived. Reopening should reflect actual state, not a cached granted flag. Secure-context, browser and operating-system restrictions vary. Link to supported setup instructions without bypassing security warnings or telling users to broadly disable protections.
- 5. Verify without collecting real private data — Use a fixture image and exercise grant, refusal, no device and revocation. Check that the fallback works and capture stops when requested. Do not upload a real receipt merely to test the flow. This guide covers interaction boundaries, not legal consent or native-device certification. A mocked permission test does not establish behavior on every physical phone.

## 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 — Verify in your product
- The request follows an intentional action.
- Only necessary access is requested.
- Granted and active differ.
- Refusal retains a usable alternative.
- Leaving stops capture.
- Upload and retention are explained separately.

## 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:999c79bee7d7df26e293e390a9833b41c2d8e6aa689bd7d1ec7ddd96c1c6270e