config-review-flow（配置审核流程）

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