Config Review Flow

Use this skill when the user wants a configuration topic reviewed and finalized one item at a time.

Workflow

1. Define the review scope first.
• Name the exact configuration topic under review.
• State what is in scope and what is out of scope.
• If the user mixes multiple topics, split them before continuing.
• If the target system, file, product, or environment is unclear, pause and clarify before collecting items.

1. Collect all configurable items from trusted sources before making recommendations.
• Prefer a sub-agent for discovery when the topic is non-trivial, broad, or documentation-heavy.
• Trusted sources mean current local config files and local docs first, then official docs if needed.
• Include detected runtime or environment facts and authoritative source-code defaults when they are part of the real configuration surface.
• Build a normalized inventory of configurable items, current or detected values if known, valid options, defaults if known, constraints, dependencies, restart or reload impact, and source links or file paths.
• Mark unknowns explicitly instead of guessing.
• Do not start recommending values before this inventory exists.

1. Normalize and de-duplicate the inventory.
• Merge duplicate items that appear across multiple sources.
• Separate true user-facing choices from internal implementation details.
• Group related items when that improves review order, but keep each final decision atomic.
• Call out prerequisites, mutually exclusive options, and settings that only matter when another item is enabled.

1. Present the full inventory to the user for review.
• Keep it compact.
• Show the whole decision surface before starting item-by-item confirmation.
• For large topics, present a grouped overview instead of dumping every detail at once, but make it clear that the full in-scope inventory has been covered.
• Highlight missing information, risky items, and irreversible or restart-sensitive settings.
• Tell the user that if the list looks right, the next step is item-by-item confirmation.

1. After the user confirms the inventory, create a tracking file under workspace/configuring/.
• Create the folder if it does not exist.
• Name the file after the configuration topic in kebab-case, for example browser.md or openclaw-browser.md.
• Record the normalized inventory before starting the walkthrough.
• Record the review scope, target environment, and any unresolved unknowns at the top.

1. Walk through one item at a time.
• Review items in dependency order, not arbitrary order.
• For each item, explain:
• what it controls
• valid options
• default if known
• important tradeoffs
• dependencies or downstream effects
• whether it needs restart, reload, migration, or no runtime action
• your recommended choice and why
• Keep one message focused on one decision unless two items are inseparable.
• Ask for confirmation on that single item.
• If the user is unsure, offer the best 2-3 options and recommend one.
• After the user confirms, write the confirmed value under that item in the tracking file before moving on.
• Then ask about the next item.

1. Handle revisions and branching explicitly.
• If the user changes an earlier decision, update the tracking file immediately.
• Re-evaluate downstream items that depend on the changed choice.
• If a new item is discovered mid-review, add it to the inventory first, then continue.
• If documentation conflicts, surface the conflict plainly and resolve it before continuing.

1. Use an explicit review state machine.
• Track the overall review state as one of: inventory, in-review, awaiting-final-confirmation, or approved-to-apply.
• Stay in inventory until the item inventory is complete and user-approved for walkthrough.
• Move to in-review when item-by-item confirmation starts.
• As soon as every in-scope item is marked confirmed or explicitly not-applicable, automatically switch to awaiting-final-confirmation.
• Do not wait for the user to ask for a summary.
• If a new item, conflict, or dependency issue appears before apply approval, leave awaiting-final-confirmation, return to in-review, update the tracking file, and only re-enter final confirmation after the review is fully confirmed again.
• Only switch to approved-to-apply after a fresh explicit apply confirmation from the user after the final summary.
• approved-to-apply means apply permission has been granted. It does not mean the real configuration has already been changed.

1. Trigger the final pre-apply confirmation automatically and stop there.
• Immediately summarize the completed plan from the tracking file when the review enters awaiting-final-confirmation.
• Separate decisions, assumptions, unresolved risks, and runtime impact.
• Then ask for one last explicit confirmation before any real config file is modified or any service is restarted, reloaded, migrated, or deployed.
• Treat this final confirmation as mandatory, even if the user previously said things like go ahead, use your judgment, apply defaults, or gave broad approval earlier in the review.
• Do not treat per-item confirmations as permission to apply the real configuration.
• While in awaiting-final-confirmation, do not continue with new recommendations, new item walkthrough, real config edits, or execution.

Operating rules

• Prefer local documentation over web search.
• Use official documentation only when local docs are missing, unclear, or outdated.
• Use a sub-agent for the discovery or inventory step when the topic is non-trivial.
• Keep the inventory separate from recommendations.
• Do not skip directly to editing the real target config file during review.
• The configuring/ markdown file is the source of truth for the in-progress review.
• If the user changes an earlier decision, update the tracking file immediately.
• If a setting requires restart, reload, migration, deploy, or downtime, mention that clearly, but do not perform it until the final apply confirmation.
• Distinguish facts from recommendations. Facts come from sources. Recommendations are your judgment.
• Do not invent defaults, supported values, or compatibility claims when sources are missing.
• Keep each decision atomic. Avoid asking the user to approve a large bundle unless the settings are inseparable.
• When the user only wants review, stop at the final pre-apply confirmation boundary.
• Final confirmation mode must trigger automatically when the review reaches a fully confirmed state.
• awaiting-final-confirmation is a hard stop. Do not modify the real target config, restart services, reload processes, run migrations, or deploy changes until the user gives a fresh explicit apply confirmation after the final summary.
• Broad earlier consent does not waive the final confirmation step.
• If a newly discovered item, conflict, or dependency issue appears while in awaiting-final-confirmation, move back to in-review before continuing.

Suggested tracking file format

Use this structure unless the topic needs a better one:

Mechanical constraints:

• Every in-scope item must appear in both Source inventory and Decisions.
• Keep item names aligned across Source inventory and Decisions.
• If any in-scope item is still pending, the overall review status must not move to awaiting-final-confirmation.

# <Topic>

- scope: ...
- target: ...
- status: inventory | in-review | awaiting-final-confirmation | approved-to-apply

## Unknowns
- ...

## Source inventory
### <item-name>
- current/detected value: ...
- options: ...
- default: ...
- dependencies: ...
- risk level: low | medium | high | unknown
- irreversible: yes | no | unknown
- requires-user-input: yes | no
- runtime impact: restart | reload | migration | deploy | none | unknown
- notes: ...
- sources: ...

## Decisions
### <item-name>
- status: pending | confirmed | not-applicable
- chosen: ...
- rationale: ...
- confirmed-at: ...
- last-updated-at: ...
- revision-notes: ...
- downstream-checks: ...

Quality bar

A review is not complete until all of these are true:

• the exact review scope is defined
• every configurable item in scope has been inventoried
• duplicates and dependency relationships have been normalized
• every item has been explained to the user
• every confirmed item has been written to the tracking file
• revisions and dependency impacts have been reflected in the tracking file
• the review state has been advanced correctly through inventory, in-review, and awaiting-final-confirmation
• the final assembled plan has been summarized from the tracking file immediately after the review reaches a fully confirmed state
• runtime impact has been summarized clearly
• final confirmation mode has been triggered automatically
• no real apply action has started before a fresh explicit apply confirmation after the final summary
• only after the final summary and a fresh explicit apply confirmation may the review state move to approved-to-apply
• the user has been asked for a last pre-apply confirmation