@ai-content-space/loopx 0.2.2 → 0.2.4

package/plugins/loopx/skills/finish/SKILL.md

@@ -3,7 +3,7 @@ name: finish
 description: "Finishes completed loopx development work after tests pass by presenting merge, PR, keep, or discard options. Not for unfinished work or failing verification."
 when_to_use: "implementation complete, tests pass, finish branch, create pull request, merge locally, keep branch, discard work"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Finish

package/plugins/loopx/skills/fix-review/SKILL.md

@@ -3,7 +3,7 @@ name: fix-review
 description: "Handles received code review feedback with verification, technical evaluation, pushback, and one-item-at-a-time fixes. Not for requesting a new review or implementing unrelated changes."
 when_to_use: "fix-review, received code review feedback, review comments, reviewer suggestions, requested changes, 处理评审意见"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Fix Review

package/plugins/loopx/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Go Style
@@ -59,7 +59,13 @@ Choose the one already used in the codebase.
 
 - Exported symbols should have Go doc comments that start with the symbol name.
 - Short local comments are acceptable when they explain why, not what.
-- Prefer complete sentences for package, exported type, exported function, and non-obvious behavior comments.
+- Prefer complete sentences for package, exported type, exported function, exported method, and non-obvious behavior comments.
+- Match new comments to the user's requested language. If the user asks in Chinese or explicitly requests Chinese comments, write new comments in Chinese while preserving Go doc naming conventions such as `// UserService ...` and `// CreateUser ...`.
+- Do not translate existing comments unless the user explicitly asks for translation; preserve the surrounding file's established comment language when no user preference is stated.
+- Remove comments that only restate syntax, names, or immediately obvious control flow.
+- Add comments for non-obvious business rules, ordering constraints, compatibility behavior, concurrency assumptions, performance tradeoffs, and external API quirks.
+- Check nearby existing comments when behavior changes; stale comments are worse than missing comments.
+- Prefer clearer names, smaller functions, or stronger types over comments that explain avoidable confusion.
 
 ## Verification
 

package/plugins/loopx/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Kratos

package/plugins/loopx/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates bite-sized implementation plans from approved requirements, clarify output, or design specs with exact files, tests, commands, expected output, and execution handoff. Not for unresolved requirements, design decisions, PRD generation, or code changes."
 when_to_use: "plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 argument-hint: "<design spec path or feature name>"
 ---
 
@@ -156,13 +156,13 @@ Plan complete and saved to `docs/loopx/plans/<filename>.md`.
 
 Two execution options:
 
-1. Subagent-Driven (recommended) - dispatch a fresh subagent per task, review between tasks, fast iteration
+1. Subagent Exec (recommended) - dispatch a fresh subagent per task, review between tasks, fast iteration
 2. Inline Execution - execute tasks in this session using exec, batch execution with checkpoints
 
 Which approach?
 ```
 
-If Subagent-Driven is chosen:
+If Subagent Exec is chosen:
 
 - REQUIRED SUB-SKILL: Use `loopx:subagent-exec`
 - Fresh subagent per task plus two-stage review

package/plugins/loopx/skills/refactor-plan/SKILL.md

@@ -3,7 +3,7 @@ name: refactor-plan
 description: "Creates a behavior-preserving refactor plan with user interview, repo evidence, tiny commits, scope boundaries, and testing decisions. Not for feature changes or immediate implementation."
 when_to_use: "refactor-plan, refactor request, refactoring RFC, tiny commits, behavior-preserving cleanup, architecture cleanup, 重构计划"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.

package/plugins/loopx/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: "Dispatches a loopx code reviewer subagent against a concrete git range and requirements. Not for implementation, planning, or unresolved review scope."
 when_to_use: "request code review, completed task review, major feature review, pre-merge review, subagent code quality check"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Review

package/plugins/loopx/skills/spec/SKILL.md

@@ -3,7 +3,7 @@ name: spec
 description: "Writes software design specs from already-clarified requirements, including solution approach, architecture outline, detailed design, tradeoffs, verification design, and handoff context. Not for unresolved requirements, PRD generation, implementation task planning, or code changes."
 when_to_use: "spec, design spec, technical design, design proposal, detailed design, architecture design, 设计方案, 概要设计, 详细设计, 技术方案"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # loopx Spec

package/plugins/loopx/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Subagent Exec

package/plugins/loopx/skills/subagent-exec/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
-  display_name: "Subagent-Driven Development"
-  short_description: "Execute implementation plans with staged subagent reviews"
+  display_name: "Subagent Exec"
+  short_description: "Execute loopx plans with staged subagent reviews"

package/plugins/loopx/skills/subagent-exec/codex-subagents.md

@@ -17,7 +17,7 @@ Use this reference before executing this skill in Codex.
 
 Subagent dispatch requires Codex multi-agent support. If `spawn_agent`,
 `wait_agent`, or `close_agent` are unavailable, do not pretend this skill ran
-as subagent-driven development. Use `loopx:exec` instead.
+as subagent-exec. Use `loopx:exec` instead.
 
 Codex environments that require explicit feature flags should enable:
 

package/plugins/loopx/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Test-Driven Development (TDD)

package/plugins/loopx/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Verification Before Completion

package/scripts/codex-workflow-hook.mjs

@@ -31,7 +31,6 @@ function nextSkill(state) {
   if (!state || !state.slug) {
     return null;
   }
-  const reviewBuildCommand = `$build --from-review .loopx/workflows/${state.slug}/review-report.md`;
   if (isClarifyReadyForPlan(state)) {
     return `$plan ${state.slug}`;
   }
@@ -51,7 +50,7 @@ function nextSkill(state) {
     && state.current_stage === 'plan'
     && Array.isArray(state.plan_blockers)
     && state.plan_blockers.length === 0) {
-    return `$build .loopx/plans/requirements-snapshot-${state.slug}.md`;
+    return `$subagent-exec .loopx/plans/requirements-snapshot-${state.slug}.md`;
   }
   if (state.current_stage === 'build'
     && state.stage_status === 'awaiting-approval'
@@ -71,13 +70,13 @@ function nextSkill(state) {
       || state.approval?.build === 'requested'
       || state.approval?.build === 'approved'
     )) {
-    return reviewBuildCommand;
+    return null;
   }
   if (state.current_stage === 'review'
     && state.review_verdict === 'request-changes'
     && state.requested_transition === 'review->build'
     && state.approval?.build === 'approved') {
-    return reviewBuildCommand;
+    return null;
   }
   if (state.current_stage === 'review'
     && state.review_verdict === 'request-changes'
@@ -94,6 +93,36 @@ function nextSkill(state) {
   return null;
 }
 
+function nextCli(state) {
+  if (!state || !state.slug) {
+    return null;
+  }
+  if (state.stage_status === 'awaiting-approval'
+    && state.current_stage === 'plan'
+    && Array.isArray(state.plan_blockers)
+    && state.plan_blockers.length === 0) {
+    return `loopx build .loopx/plans/requirements-snapshot-${state.slug}.md`;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.rollback_target === 'build'
+    && (
+      state.pending_user_decision === 'review->build'
+      || state.requested_transition === 'review->build'
+      || state.approval?.build === 'requested'
+      || state.approval?.build === 'approved'
+    )) {
+    return `loopx build --from-review .loopx/workflows/${state.slug}/review-report.md`;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->build'
+    && state.approval?.build === 'approved') {
+    return `loopx build --from-review .loopx/workflows/${state.slug}/review-report.md`;
+  }
+  return null;
+}
+
 function blockers(state) {
   const values = [
     ...(Array.isArray(state.plan_blockers) ? state.plan_blockers : []),
@@ -134,7 +163,7 @@ function nextActionLine(state, workflow) {
   if (isClarifyReadyForPlan(state) && state.approval?.plan !== 'approved') {
     return `approve clarify -> plan, then $plan ${state.slug || workflow}`;
   }
-  return nextSkill(state) || state.recommended_next_action || 'none';
+  return nextSkill(state) || nextCli(state) || state.recommended_next_action || 'none';
 }
 
 function implementationGateLines(state) {
@@ -228,6 +257,8 @@ try {
     `loopx workflow: ${state.slug || workflow}`,
     `stage: ${stageText(state)}`,
     `next: ${nextActionLine(state, workflow)}`,
+    `next skill: ${nextSkill(state) || '(none)'}`,
+    `next cli: ${nextCli(state) || '(none)'}`,
     `blockers: ${blockers(state)}`,
     ...implementationGateLines(state),
     `approval: ${JSON.stringify(state.approval || {})}`,

package/skills/RESOLVER.md

@@ -26,6 +26,7 @@ Read the selected skill file before acting. If multiple skills match, read every
 | Feature or bugfix implementation should be covered by a failing test first | `skills/tdd/SKILL.md` |
 | Bug, test failure, build failure, regression, unexpected behavior, root-cause investigation | `skills/debug/SKILL.md` |
 | Completion, fixed, passing, review-ready, commit, or handoff claims need fresh evidence | `skills/verify/SKILL.md` |
+| Document readability, PRD assessment, requirements gaps, unclear viewpoint, AI-like prose, or document rewriting | `skills/doc-readability/SKILL.md` |
 | Editing `.go` files or reviewing Go style | `skills/go-style/SKILL.md` |
 | Go-Kratos proto, service, biz, data, middleware, auth, config, or troubleshooting | `skills/kratos/SKILL.md` |
 
@@ -42,7 +43,8 @@ Read the selected skill file before acting. If multiple skills match, read every
 9. Use `fix-review` only after feedback exists.
 10. Use `finish` only after implementation, final review, and verification are complete.
 11. Use `refactor-plan` for behavior-preserving refactor planning. If the refactor changes external behavior or contracts, route to `clarify` or `spec`.
-12. Treat `tdd`, `debug`, `verify`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
+12. Use `doc-readability` for document assessment or rewriting, especially PRDs, requirements docs, specs, meeting notes, and AI-like prose. If the document is a source artifact for implementation, assess or rewrite it first, then route clarified implementation work back through `clarify`, `spec`, or `plan`.
+13. Treat `tdd`, `debug`, `verify`, `doc-readability`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
 
 ## Deterministic Guard
 

package/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # loopx Clarify

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.2.2"
+  version: "0.2.4"
 ---
 
 # Systematic Debugging

package/skills/doc-readability/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: doc-readability
+description: "Use when evaluating, rewriting, or editing documents for human readability, unclear viewpoints, AI-like prose, bloated specs, PRDs, requirements docs, meeting notes, strategy docs, or internal knowledge-base articles. Not for code review, implementation planning, or file-format conversion."
+when_to_use: "document readability, PRD assessment, requirements gaps, AI-like prose, unclear viewpoint, rewrite docs, editing docs, 文档可读性, 去AI味, 需求文档评估"
+metadata:
+  version: "0.2.4"
+---
+
+# Doc Readability
+
+## Principle
+
+Readable documents help a specific reader make a decision, execute work, or verify a claim with minimal reconstruction. Do not confuse readability with shortness or smooth prose. Preserve factual meaning, domain vocabulary, and useful specificity while removing noise.
+
+## First Move
+
+Read the actual document before judging it. If the document is a URL, cloud doc, wiki page, local file, PDF, or exported artifact, fetch or read the content with the appropriate available tool. If only an excerpt is provided, state that the assessment is based on the excerpt.
+
+Start by inferring:
+
+| Question | Why it matters |
+|---|---|
+| Who is the reader? | Reviewers, engineers, operators, executives, and future maintainers need different structures. |
+| What job must the document do? | PRDs, engineering specs, SOPs, decision memos, and general notes have different standards. |
+| What is the main claim? | If the claim is hard to state in one sentence, the document likely has a structure problem. |
+| What action should follow? | Readability is poor when the reader cannot tell what to do next. |
+
+If these are clear from the request and document, use them to make a recommendation. The document type still needs user confirmation unless the user explicitly asks for a quick assessment or says to use judgment.
+
+## Setup Flow
+
+User choices override inference. Support explicit inputs such as:
+
+```text
+Document type: engineering spec
+Reader: engineering reviewers
+Mode: assessment only
+Strictness: review-ready
+```
+
+Do not turn setup into a form. Use this order:
+
+1. Confirm document type first. If the user has not explicitly specified document type, ask Step 1 before evaluating. Do not proceed based only on inference.
+2. If the document appears to mix multiple types, ask which lens should be primary. Do not silently choose the primary type.
+3. After document type is chosen, read enough of the document to judge its actual condition: title, headings, first screen, conclusion, and key sections. For long documents, sample the main path and high-risk sections.
+4. Only after reading the document may the agent recommend an action mode. Do not recommend assessment-only, targeted suggestions, or rewrite before reading the document.
+5. Recommendations must be dynamic, based on the user request, chosen document type, document content, headings, visible structure, and previous user choices.
+6. Do not hard-code a default recommendation in the skill.
+7. If the user says "quick assessment", "use your judgment", "don't ask", or equivalent, proceed with inference and state assumptions.
+
+Ask setup questions sequentially:
+
+```text
+I want to confirm the document type. Based on the title and headings, I would treat this as "...", because ...
+
+Which document type should I use?
+1. Engineering spec / interface contract / rules document
+2. Requirements document / PRD
+3. Engineering design document
+4. SOP / operating procedure
+5. Decision memo
+6. Research / analysis document
+7. Meeting notes / discussion record
+8. Postmortem / RCA
+9. Project plan / roadmap
+10. General note / knowledge-base article
+```
+
+After the user chooses the type, read the document. Then decide whether action mode needs confirmation:
+
+```text
+I have read the document's main path. Given the chosen type and the document's actual condition, I recommend "...", because ...
+
+How should I handle it?
+1. Assessment only
+2. Assessment plus targeted improvement suggestions
+3. Assessment, then rewrite only if there are blocking issues
+4. Rewrite directly
+```
+
+Ask strictness only when it would change the result:
+
+```text
+Strictness will affect this assessment. I recommend "...", because ...
+
+Which strictness should I use?
+1. Usable for internal handoff
+2. Review-ready
+3. Publication-ready
+```
+
+If strictness is not worth asking, choose a sensible default and state it briefly.
+
+When the confirmed document type is `Requirements document / PRD`, read `references/prd.md` before assessment or rewrite. Use it to check requirement completeness and testability, not just prose clarity.
+
+## Document Types
+
+Use the document type to set the evaluation bar.
+
+| Type | Readability standard |
+|---|---|
+| Requirements / PRD | Reader can identify problem, users, goals, non-goals, scope, workflows, requirements, acceptance criteria, priorities, and open questions. Also read `references/prd.md` for PRD-specific completeness checks. |
+| Engineering design | Reader can identify context, proposed design, key decisions, rejected alternatives, contracts, data flow, failure modes, rollout, and boundaries. |
+| Engineering spec / interface contract / rules document | Reader can identify the first-screen conclusion, main decision path, canonical rules, field/status definitions, and where details live. Long tables, enum lists, field contracts, state tables, and long sections are acceptable when they are locatable and support implementation. Judge clarity of path and lookup, not shortness. |
+| SOP / operating procedure | Reader can identify trigger, owner, prerequisites, step order, checks, exceptions, and escalation path. |
+| Decision memo | Reader can identify recommendation, rationale, tradeoffs, risks, decision owner, and next action. |
+| Research / analysis | Reader can identify question, method, evidence, conclusion, confidence, limitations, and implications. |
+| Meeting notes / discussion record | Reader can identify decisions, unresolved questions, owners, due dates, and context needed later. |
+| Postmortem / RCA | Reader can identify impact, timeline, root cause, contributing factors, fixes, owners, and prevention checks. |
+| Project plan / roadmap | Reader can identify objective, milestones, dependencies, owners, risks, dates, and decision points. |
+| General note / knowledge-base article | Reader can identify topic, takeaway, section map, and why each section exists. |
+
+If a document mixes types, name the primary and secondary type. Judge the primary reading path first; suggest moving secondary material to an appendix or companion doc only when it interferes with the main job.
+
+## Diagnostic Rubric
+
+Evaluate across these dimensions:
+
+| Dimension | Good | Poor |
+|---|---|---|
+| Viewpoint | The document makes defensible claims and repeats them consistently. | It lists related facts without choosing what matters. |
+| Reader path | The reader can predict where conclusions, rules, examples, and details live. | Background, rules, fields, cases, and tasks are mixed together. |
+| Information hierarchy | Important decisions appear first; details support them. | Long tables and sections force the reader to synthesize conclusions manually. |
+| Actionability | Owners, timing, inputs, outputs, states, and exceptions are concrete. | Sentences say "support", "process", "handle", or "optimize" without operational meaning. |
+| Density | Each paragraph changes what the reader knows or can do. | Repeated sentence frames and generic transitions create drag. |
+| Boundary clarity | Scope, non-goals, risks, blockers, and "not automatic" rules are explicit. | Boundaries are scattered, softened, or buried after implementation detail. |
+| Human voice | The prose shows judgment, tradeoffs, and emphasis. | The prose is neutral, padded, symmetric, and unwilling to choose. |
+
+Lead with a practical verdict in the user's language: `Readable`, `Partly readable`, or `Hard to read`.
+
+Separate findings by severity:
+
+| Severity | Meaning |
+|---|---|
+| Blocking | The target reader cannot understand the conclusion, decision path, required action, or authoritative rule. This usually requires restructuring or rewriting. |
+| Important | The document is usable, but readers will waste time or may implement inconsistently. Recommend focused changes. |
+| Optional | The document can be improved, but the issue does not block review or execution. Do not present optional polish as readability failure. |
+
+For an already rewritten or structured document, use this severity split instead of listing every possible flaw as a main obstacle.
+
+## AI-Like Smells
+
+Treat these as signals to tighten or restructure:
+
+- Broad openings like "This document is used to..." without a decision.
+- Repeated section patterns that say the same thing for every case.
+- Tables whose cells are long paragraphs.
+- Grammatically parallel bullets that are not intellectually prioritized.
+- Generic terms like `support`, `process`, `optimize`, `capability`, `workflow`, `closed loop`, `improve`, `ensure`.
+- Every section ending with "notes" that restate prior content.
+- Long chains of "need to / can / generate / receive / process" without owner, timing, or output.
+- Balanced summaries that avoid saying "do this", "do not do this", or "this is the rule".
+
+Do not remove domain terms merely because they are technical. Remove vagueness, not expertise.
+
+## Rewrite Strategy
+
+Choose structure by document job:
+
+| Job | Preferred shape |
+|---|---|
+| Requirements / PRD | Problem -> users -> goals/non-goals -> scope -> workflows -> requirements -> acceptance criteria -> open questions |
+| Engineering design | Context -> decision -> architecture -> alternatives -> contracts -> data flow -> failure modes -> rollout |
+| Engineering spec / contract / rules | Conclusion -> hard rules -> decision path -> canonical definitions -> field/status contracts -> examples -> appendix |
+| SOP | Trigger -> owner -> prerequisites -> steps -> checks -> exceptions -> escalation |
+| Decision memo | Verdict -> decisions -> tradeoffs -> risks -> next action -> appendix |
+| Research / analysis | Question -> method -> evidence -> findings -> confidence -> limitations -> implications |
+| Meeting notes | Context -> decisions -> action items -> open questions -> reference notes |
+| Postmortem / RCA | Impact -> timeline -> root cause -> contributing factors -> fixes -> prevention |
+| General note / KB | Orientation -> key takeaway -> section map -> details |
+
+For long documents, do not polish in place first. Extract the spine:
+
+1. One-sentence main claim.
+2. Three to seven decisions or rules.
+3. Who owns each action.
+4. Which details belong in appendix/reference.
+5. Which repeated sections can share one template.
+
+Then rewrite only within the user-approved action mode.
+
+## Output Rules
+
+Match the user's requested mode. Use natural headings in the user's language. Do not expose rigid labels like `Main claim I extracted`, `Main reading obstacles`, or `Rewritten version` unless the user asks for a machine-readable template.
+
+For assessment, cover:
+
+- Chosen or inferred setup.
+- Readability verdict.
+- Core viewpoint extracted from the document.
+- Blocking issues, important improvements, and optional polish.
+- Whether rewrite is recommended.
+
+Rewrite control:
+
+- If mode is `assessment only`, do not output a rewritten version. State whether rewrite is recommended.
+- If mode is `assessment plus targeted suggestions`, provide focused changes, not a full rewrite.
+- If mode is `rewrite only if blocking`, provide a rewritten version only when blocking issues exist.
+- If mode is `rewrite directly`, rewrite directly with a short diagnosis first.
+- For long documents, rewrite the most important section first unless the user explicitly asks for the full document.
+
+## Editing Rules
+
+- Lead with conclusions and rules before explanation.
+- Prefer prose over a table when table cells become paragraphs.
+- Split source-of-truth rules from implementation details.
+- Make negative rules explicit: "do not auto-post cash", "do not rewrite historical trades", "do not send Plan before confirmation".
+- Replace repeated prose with one shared rule plus event-specific exceptions.
+- Keep strong domain nouns, exact dates, fields, statuses, and enumerations.
+- Preserve real uncertainty, but name what is unknown and who resolves it.
+- Remove performative transitions unless they add structure.
+- Do not make formal documents chatty. Human writing means judgment and economy, not casual tone.
+
+## Final Check
+
+Before claiming the document is improved, verify:
+
+- The main claim is visible in the first screen or first section.
+- A new reader can state the next action after reading the conclusion.
+- Repeated content has been collapsed or justified.
+- Boundaries and non-goals are not buried.
+- Any removed text was redundant, not a lost requirement.