j4k-oss/agent-skills
Watch
1
0
Fork
You've already forked agent-skills
 0
Code Issues 6 Pull requests Releases Packages Activity Actions

fix: documentation skills should preserve detail readers need #130

Merged
jercik merged 1 commit from fix/doc-fact-authority into main 2026-10-08 17:29:07 +00:00
Conversation 2 Commits 1 Files changed 2 +14 -7
jercik commented 2026-10-08 17:14:58 +00:00
Owner
Copy link

Gives documentation authors one standard for fact ownership and reader needs. Necessary contracts, warnings, and derived values stay where readers act; unnecessary maintenance copies still require removal. These instructions are already included in the deployed reviewer hotfix.

The suite passes 172 of 173 tests; the keeper-path assertion in audit-checkouts.test.mjs:2248 also fails on main.

Merge before the runner pin update. Its check:skill-pin requires both complete skill directories at the pinned revision to match the default branch. Squash or rebase merges work if those directories remain identical.

Gives documentation authors one standard for fact ownership and reader needs. Necessary contracts, warnings, and derived values stay where readers act; unnecessary maintenance copies still require removal. These instructions are already included in the deployed reviewer hotfix. The suite passes 172 of 173 tests; the keeper-path assertion in `audit-checkouts.test.mjs:2248` also fails on `main`. Merge before the runner pin update. Its `check:skill-pin` requires both complete skill directories at the pinned revision to match the default branch. Squash or rebase merges work if those directories remain identical.
fix: reconcile fact authority with reader needs
All checks were successful
commit-msg / commitlint (pull_request) Successful in 25s
Details
Node tests / node:test (pull_request) Successful in 3m12s
Details
Review / Review (pull_request_target) Successful in 3m22s
Details
c40df477f3
forgejo-actions commented 2026-10-08 17:18:20 +00:00
Copy link

Review 01M4E85RQ2W046Y9J9H3BACAAX — head c40df477f3d6989e0fddb2e393164c94d400b347

Review — j4k-oss/agent-skills @ f3c2243da4

Scope: diff against base tree 8e004ccf90c2
Status: dispatched — coverage complete (4/4 slots terminal)
Facts: current review-wide projection

Computed under:

{
  "abandonment": "abandonment-v1",
  "anchor_recipe": 1,
  "batch_policy": "batch-v1",
  "coverage": "coverage-v3",
  "dispatch_policy": "dispatch-v2",
  "grounder_version": 1,
  "grounding_read_rule": "grounding-read-v1",
  "promotion_policy": "promotion-v1",
  "report": "report-v4",
  "tally": "tally-v1",
  "triage_settle": "triage-settle-v2"
}

Findings (0)

No findings survived.

Reviewed:

  • general-bug (whole/default): no-claims
  • writing-quality (whole/default): claims-emitted
  • restated-sets (whole/default): no-claims
  • project-docs (whole/default): no-claims
  • test-trimming: skipped-by-dispatch — no tests changed; only skill documentation modified

Other claims

  • grounding-pending (0)
  • ungrounded (0)
  • rejected (0)
  • duplicate-of (0)
  • unadjudicated (2)
    • 01M4E87N1RP6KVRTT7DP70H52F low — project-docs states the one-authority/task-serving-copy rule three times in the same file
    • 01M4E87WCXJFG2TP9WDRD0RF7Z low — writing-for-agents' new 'One Idea, One Place' paragraphs repeat each other and add reviewer-facing no-op sentences

Coverage

Coverage pass: 01M4E8681JVPDWRZSJXXZJMQR4
Accounting: complete
Slot health: healthy

lens part arm unit status runs loss
general-bug whole default no-claims 1 no
writing-quality whole default claims-emitted 1 no
restated-sets whole default no-claims 1 no
project-docs whole default no-claims 1 no
  • test-trimming — skipped-by-dispatch: no tests changed; only skill documentation modified
<!-- review:summary --> **Review** `01M4E85RQ2W046Y9J9H3BACAAX` — head `c40df477f3d6989e0fddb2e393164c94d400b347` # Review — j4k-oss/agent-skills @ f3c2243da4c8 Scope: diff against base tree `8e004ccf90c2` Status: dispatched — coverage complete (4/4 slots terminal) Facts: current review-wide projection Computed under: ```json { "abandonment": "abandonment-v1", "anchor_recipe": 1, "batch_policy": "batch-v1", "coverage": "coverage-v3", "dispatch_policy": "dispatch-v2", "grounder_version": 1, "grounding_read_rule": "grounding-read-v1", "promotion_policy": "promotion-v1", "report": "report-v4", "tally": "tally-v1", "triage_settle": "triage-settle-v2" } ``` ## Findings (0) No findings survived. Reviewed: - general-bug (whole/default): no-claims - writing-quality (whole/default): claims-emitted - restated-sets (whole/default): no-claims - project-docs (whole/default): no-claims - test-trimming: skipped-by-dispatch — no tests changed; only skill documentation modified ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (2) - `01M4E87N1RP6KVRTT7DP70H52F` low — project-docs states the one-authority/task-serving-copy rule three times in the same file - `01M4E87WCXJFG2TP9WDRD0RF7Z` low — writing-for-agents' new 'One Idea, One Place' paragraphs repeat each other and add reviewer-facing no-op sentences ## Coverage Coverage pass: 01M4E8681JVPDWRZSJXXZJMQR4 Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | whole | default | claims-emitted | 1 | no | | restated-sets | whole | default | no-claims | 1 | no | | project-docs | whole | default | no-claims | 1 | no | - test-trimming — skipped-by-dispatch: no tests changed; only skill documentation modified
🚀 1
jercik commented 2026-10-08 17:28:24 +00:00
Author
Owner
Copy link

Investigated both unadjudicated low-severity claims against the full changed skills at c40df477f3d6989e0fddb2e393164c94d400b347:

  • 01M4E87N1RP6KVRTT7DP70H52F: the three project-docs passages govern different operations. Division of labor chooses a fact's authority and permits task-serving presentations; maintenance routes stray-document duplicates into the scoped consolidation workflow; consolidation requires moving before removal, preserves necessary local meaning, deletes empty files, and prohibits information loss. Removing those later instructions merely because they apply the same principle would remove distinct operational constraints. The shared principle is consistent across them; repeated subject matter alone does not establish a redundant instruction.
  • 01M4E87WCXJFG2TP9WDRD0RF7Z: the new writing paragraphs distinguish derived displays, task-required exact details, when a source lookup is sufficient, and when a manual copy should be removed. These answer different decisions, including the diagnostic/interface and source-access boundaries needed to prevent the observed contradictory reviews. This skill explicitly serves both writing and reviewing agent instructions, so those review-facing boundaries are within its stated audience. No sentence identified by the report can be removed on the title's evidence without first showing that its boundary is preserved elsewhere.

Neither claim demonstrates a defect in this revision. Retaining these distinct constraints preserves the accepted behavior; this is not a general exemption from removing redundant instructions.

Investigated both unadjudicated low-severity claims against the full changed skills at `c40df477f3d6989e0fddb2e393164c94d400b347`: - `01M4E87N1RP6KVRTT7DP70H52F`: the three project-docs passages govern different operations. Division of labor chooses a fact's authority and permits task-serving presentations; maintenance routes stray-document duplicates into the scoped consolidation workflow; consolidation requires moving before removal, preserves necessary local meaning, deletes empty files, and prohibits information loss. Removing those later instructions merely because they apply the same principle would remove distinct operational constraints. The shared principle is consistent across them; repeated subject matter alone does not establish a redundant instruction. - `01M4E87WCXJFG2TP9WDRD0RF7Z`: the new writing paragraphs distinguish derived displays, task-required exact details, when a source lookup is sufficient, and when a manual copy should be removed. These answer different decisions, including the diagnostic/interface and source-access boundaries needed to prevent the observed contradictory reviews. This skill explicitly serves both writing and reviewing agent instructions, so those review-facing boundaries are within its stated audience. No sentence identified by the report can be removed on the title's evidence without first showing that its boundary is preserved elsewhere. Neither claim demonstrates a defect in this revision. Retaining these distinct constraints preserves the accepted behavior; this is not a general exemption from removing redundant instructions.
🚀 1
jercik merged commit 495c966a5a into main 2026-10-08 17:29:07 +00:00
jercik deleted branch fix/doc-fact-authority 2026-10-08 17:29:07 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
j4k-oss/agent-skills!130
No description provided.