Skip to content

docs: check for existing Nextcloud capabilities before writing new logic - #104

Merged
moodyjmz merged 3 commits into
mainfrom
docs/agents-check-existing-nc-capabilities
Aug 10, 2026
Merged

docs: check for existing Nextcloud capabilities before writing new logic#104
moodyjmz merged 3 commits into
mainfrom
docs/agents-check-existing-nc-capabilities

Conversation

@moodyjmz

Copy link
Copy Markdown
Contributor

Summary

Follow-up to #88. "Reuse before you write" only covered UI reuse — an @nextcloud/vue component, a design token, an existing src/ pattern. It said nothing about checking whether the server already exposes the behaviour, or whether a non-UI @nextcloud/* package already covers it.

  • Broadens the preference ladder to four steps: an existing server feature (OCP interface or protocol-level capability) → the wider @nextcloud/* npm scope, not just @nextcloud/vue@nextcloud/vue components/tokens → existing src/ patterns.
  • The OCP check is concrete and grep-able: this app vendors the full OCP stub tree via composer require-dev (nextcloud/ocpvendor/nextcloud/ocp/OCP/), so "check for an existing interface" is a real local grep, not an appeal to background knowledge an agent may not have.
  • Adds a partial-fit escape valve wired into the existing "When the call is contestable, ask" rule, so the new instruction can't be used to justify contorting a bad fit into place.
  • Folds the new rule's PR-description disclosure into the existing pre-PR checklist rather than adding another scattered "say X in the description" instance.

#100's DAV orderby/limit fix is the motivating example: the server already supported both via the DAV SEARCH grammar, so the fix was a one-file request change instead of custom client-side pagination. This rule is meant to make checking for that kind of existing capability the default first move, not a lucky diagnosis.

Process note

This draft went through an adversarial review pass before being opened. An earlier version hardcoded this app's @nextcloud/* dependency list (stale the moment a dependency changes — and a direct contradiction of the token guidance two paragraphs below it, which explicitly refuses to enumerate for that same reason), gave no verifiable method for the OCP check ("say you checked" isn't auditable), and used "capability" for two different things four lines apart. All three are fixed in this version.

Test plan

  • N/A — docs only, no code paths affected

moodyjmz and others added 2 commits August 10, 2026 11:29
"Reuse before you write" only covered UI: an @nextcloud/vue component, a
design token, an existing src/ pattern. It said nothing about checking
whether the server already exposes the behaviour (an OCP interface, or a
raw protocol feature) or whether a non-UI @nextcloud/* package already
covers it — exactly the reuse that made #100's DAV orderby/limit fix a
one-file request change instead of custom client-side pagination.

Broaden the ladder to four steps (server capability, then the wider
@nextcloud/* npm scope, then vue components/tokens, then src/ patterns),
wire a partial-fit escape valve into the existing contestable-call rule so
the new instruction can't be forced past a bad fit, and fold its
PR-description disclosure into the existing pre-PR checklist instead of
adding another scattered "say X in the description" instance.

Went through an adversarial review pass before landing: an earlier version
hardcoded this app's @nextcloud/* dependency list (stale the moment a
dependency changes, and a direct contradiction of the token guidance two
paragraphs below it, which explicitly refuses to enumerate for that same
reason), gave no verifiable method for the OCP check ("say you checked" is
not auditable), and used "capability" for two different things four lines
apart. All three are fixed here — the OCP check now points at a real,
grep-able local path, `vendor/nextcloud/ocp/OCP/`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
Every other rule in this file explains its motivating incident in the
commit message or PR body, never inside the instructional text itself
— #79, #83, #84, and #100's own diagnosis are all discussed there, not
quoted in AGENTS.md. "see #100" broke that pattern and adds nothing:
the DAV SEARCH orderby/limit example is already self-contained, and a
bare PR number means nothing to a future reader without the context
this conversation had.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
@moodyjmz moodyjmz self-assigned this Aug 10, 2026
Signed-off-by: James Manuel <moodyjmz@users.noreply.github.com>
@moodyjmz
moodyjmz merged commit a14a022 into main Aug 10, 2026
23 checks passed
@moodyjmz
moodyjmz deleted the docs/agents-check-existing-nc-capabilities branch August 10, 2026 12:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants