Refine grounded-coding scope, progressive disclosure and completion criteria

[billster45]

Problem and intended outcome

The skill contains valuable operational guidance, but repeated requirements, broad completion rules and specialist instructions loaded for every task can cause unnecessary research, reporting or early stops. Revise it to make routine grounded work proportionate while preserving the checks needed for difficult integrations.

This is a deferred improvement proposal, not evidence that a shorter skill performs better. Keep the skill useful across models and coding agents; do not optimise solely for GPT-6 Astra.

Status: Backlog — deferred by owner.
Priority: Medium.
Issue type: Enhancement.

Reviewed baseline

Review of main at commit a34a4a8, including README, SKILL.md and both references. Refresh the baseline before implementation.

The README explicitly positions grounded-coding as a coordinator, so length alone is not a defect. Preserve that purpose.

Findings and proposed treatments

1. Unbounded completion rule. Line 143 says a task is not done if a relevant primary source exists but was not consulted. Bound completion to verifying the material external behaviour the change relies on and identifying remaining uncertainty, rather than exhausting relevant sources.
2. Repeated evidence requirements. Operating Contract, Grounded Close-Out and Definition Of Done repeat sources, validation, decisions and uncertainty. Consolidate into one evidence contract.
3. Specialist integration checklist in the main file. Preserve the Integration Proof Ladder in a conditional reference. Define a precise trigger for material integration and authorization boundaries; routine framework edits should not load every integration check.
4. Duplicated source directory. Source Routing and Primary Sources overlap with references/doc-sources.md. Keep routing conditions in SKILL.md and maintained URLs in references.
5. Decision records for every documented alternative. Lines 38–39 can turn routine choices into unnecessary tradeoff reports. Require records for material alternatives affecting behaviour, architecture, security, cost or operations.
6. One output structure imposed on chat, commits and PRs. Lines 126–141 may conflict with repository conventions and duplicate evidence. Preserve evidence requirements while adapting placement and format to the repository.
7. Maintainer guidance loaded during task execution. Move the Improvement Loop into README; it primarily guides skill maintenance rather than completion of a coding task.

Safeguards to retain

• Verify version-sensitive external behaviour before relying on it.
• Distinguish documented facts, inference and observed local results.
• Check whether accepted configuration actually reaches generated or deployed contracts.
• Separate documentation retrieval from authorization to perform operations.
• Preserve meaningful evidence and uncertainty.
• Check affected documentation and contracts when behaviour changes.
• Retain pinned-version/schema checks, adapter transformations, authorization compatibility and bootstrap permissions where applicable.
• Preserve bounded live-probe planning: prerequisites, scope, cost, stop conditions, evidence, rollback and cleanup. This issue does not authorize live probes or paid evaluations.

Proposed structure

grounded-coding/
├── SKILL.md                    # Scope, core contract, routing, evidence
└── references/
    ├── doc-sources.md           # Official documentation directory
    ├── mcp-servers.md           # Retrieval capabilities and composition
    └── integration-review.md   # Detailed integration proof ladder

Keep README consistent with the final skill. Preserve invocation policy and source-grounding intent; avoid adding a mandatory stack of skills or an arbitrary word-count target.

Acceptance and validation

• Consolidate repeated requirements without losing operational invariants.
• Make research stopping conditions and material decision-record requirements explicit.
• Ensure specialist references have precise, discoverable triggers.
• Adapt evidence output to repository conventions.
• Validate frontmatter and reference links; distinguish pre-existing validator limitations from new failures.
• Compare baseline and revised behaviour on the same representative requests: a routine SDK change, a purely local refactor, and a difficult integration review.
• Assess source correctness, unnecessary retrieval/reporting, premature stops, and preservation of integration findings—not just word count or matching headings.
• Use equivalent fixtures, model/settings and permitted side effects for the comparison. Any paid calls or live operations require separate authorization.
• Report results and remaining uncertainty before claiming the revision improves performance.

Scope

This issue records a future repository revision. No implementation, commit, PR, deployment or model evaluation is authorized by its creation. Unrelated personal skills and plugin settings are out of scope.