[jarhodes314]

NOT INTENDED TO BE MERGED if we like these changes, they ought to be incorporated into #4241

Some suggested revisions to config.yaml along with an example of what the config exposure spec can be rewritten to according to those guidelines.

The goal of this is to revise the config so it cuts out unnecessary words making the specs hard to review without brevity at the expense of clarity. The initial proposal by @albinsuresh of how to revise the config resulted in some short but essentially redundant sentences, while leaving some key details completely unmentioned. I also found the phrasing by asking for short sentences unhelpful, my impression was a lot of connecting words were discarded, making the sentences hard to parse, but not really for much gain.

Both the suggested config changes and an attempt at rewriting the spec with those rules is included. I haven't reviewed or edited this version of the spec, it's straight from claude with the goal of producing the best possible environment for

Key config changes:

• "Short declarative sentences" → "Clear, complete sentences." — The old rule produced sentence fragments that dropped the words connecting one idea to the next. Concise is good; ambiguous is not.
• "Bullets over prose" → "Bullets for lists; paragraphs for context." — Not everything is a list. When context needs to explain why two things are related, a short paragraph does that better than two bullets that lost their connection to each other.
• "Skip elaboration" → qualified with "unless non-obvious connection" — In my testing of the config, there were implicit context switches between sentences, e.g. it switched from talking about MQTT to talking about HTTP, but the only way I knew that was it started talking about 404, no mention of HTTP.
• Anti-ambiguity rule for scope statements — A non-goal discussing "Child device config exposure" could mean exposing config from child devices (non-goal) or exposing config to child devices (goal). If a phrase reads two ways, spell out which one you mean.
• "What you can do" → "Proposed solution" — "You" had no clear referent.
• Proposal ordering: introduce the capability before qualifying it — The previous rule ("never lead with an implementation detail") was too narrow. The real problem: bullets described properties of the feature (opt-in, self-correcting) before the reader knew what the feature was.
• Design Context: name the problem and constraints — The old rule said "1-3 sentence orientation, then straight to decisions." Instead of imposing somewhat arbitrary rules on the agent, this guides the agent to the details we actually want. Simply imposing a sentence limit meant that it produced a small number of sentences that didn't serve any particular purpose.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[didier-wenzek]

The outcome is indeed easier to read compared to the former result #4241

[jarhodes314]

This statement could seemingly do with some strengthening. It is indeed doing semantic line breaks, but it's also hard-wrapping sentences and I believe we want one sentence per line to make review easier.

[jarhodes314]

Closing as this is now integrated into #4241