personal-assistant-review-followup

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Personal Assistant Review Follow-up

## Core Rule

Use this skill after `personal-assistant-review` or any review that produced
findings for the current `personal-assistant` repository.

The goal is not to fix every review comment. The goal is to separate real
release risk from optional polish, get the needed decision, implement only the
confirmed fix set, and verify the result without over-claiming.

Hard boundary: do not make product decisions while fixing review findings.
If a finding can be fixed by removing, hiding, narrowing, or adding friction to
a user-facing capability, ask the user before coding unless the user already
made that exact product choice in this conversation and it still applies, or
the fix restores a current accepted product contract. An agent-authored approval
is not evidence of a user decision.

## Workflow

1. Verify each finding against its exact trigger, affected code, and current
   contract before restating it. Separate verified defects from hypotheses;
   reviewer confidence or severity is not evidence.
2. Classify each finding:
   - **must-fix**: correctness, data safety, privacy, user-visible breakage,
     product-contract violation, release blocker, or a direct failure of the
     current patch's stated goal.
   - **should-fix-now**: small, local fix that prevents a likely regression or
     stabilizes the changed behavior, even if not release-blocking.
   - **defer**: polish, theoretical failure path, localized copy cleanup
     without product-contract or safety impact, refactor preference, or risk
     without a concrete trigger.
3. Calibrate severity again against that evidence. A readability concern should
   identify a concrete change entry, responsibility, or invariant that is hard
   to follow. Style preferences or speculative risks alone do not justify a
   refactor, broader scope, or a full validation gate.
4. Identify decision points before coding.
5. If the user only asked for analysis or explicitly required read-only work,
   make no writes; stop after the classification and decision options.
6. Ask for an unresolved product decision when viable fixes materially differ
   in behavior or user effort. Reuse applicable user decisions and current
   accepted contracts; do not infer a decision from reviewer severity.
7. Implement the confirmed fix set only after the user explicitly asks to
   implement or fix it. If that authorization already exists in this conversation
   and still covers the fix set, proceed without asking again.
8. Add a regression test for the accepted runtime trigger when needed; do not
   add tests that merely assert documentation wording.
9. Validate with focused checks, then app smoke only when the changed surface
   needs deployed Obsidian evidence.

Product choices requiring a decision when not already resolved by applicable
user authority or a current accepted contract:
- Removing or hiding a visible control, command, workflow, or shortcut.
- Increasing or decreasing confirmation burden for durable, provider-backed,
  cost-bearing, privacy-sensitive, or future-behavior-changing actions.
- Choosing between safety/trust and the product goal of reducing user burden.
- Changing product copy, information architecture, queue/batch behavior, or
  review cadence in a way that changes what users can do.
- Reinterpreting a current product doc, roadmap, tracker, or user-stated
  product principle.

When an unresolved product decision appears, present the smallest viable options
with a recommendation and tradeoff. Do not continue into code edits for that
decision until the user chooses; continue independent authorized fixes.

## Decision Lens

Use three lenses when the user asks whether findings need decisions.

Architecture:
- Define ownership and invariants, not just symptoms.
- Prefer boundaries already used by the touched modules.
- If a fix only masks one UI symptom but leaves concurrent semantics undefined,
  ask for or propose the invariant.

Program:
- Decide whether the implementation should reject, serialize, dedupe, or reuse
  in-flight work.
- Prefer a minimal helper or state flag when the invariant is local.
- Avoid broad refactors unless the finding proves an existing abstraction is
  misleading or dangerous.

Product:
- Decide what the user should see and what should not happen twice.
- Protect provider-backed, cost-bearing, destructive, or persistent actions
  from accidental duplicate execution.
- Preserve the user's product intent and local product docs even when a reviewer
  suggests a safer but higher-burden alternative.
- For Memory, Review Queue, Pagelet, and other review surfaces, explicitly
  weigh the burden of extra confirmations against trust and source evidence.
- Keep ordinary copy in the product language for the touched surface. Internal
  terms are acceptable in diagnostics, logs, and developer-only output.

## Fix Discipline

- Do not fix deferred findings unless the user explicitly adds them to the
  confirmed fix set.
- Do not make opportunistic changes outside the confirmed fix set.
- Preserve user edits and existing uncommitted changes.
- Use `apply_patch` for manual edits.
- Per AGENTS.md Testing Instructions, do not claim Obsidian validation without
  deployed evidence.

## Validation

Start with the smallest checks that prove the accepted finding is fixed.
For code/DOM changes, run the **Local Validation Gate** from AGENTS.md, scoped
to the affected suites. For plugin command, worker, DOM/CSS, or shared runtime
changes, also include `npm run lint`. For documentation-only fixes, use the
relevant documentation checks and `git diff --check`; do not run runtime gates
without a runtime change.

Use **Validation Planning And Reuse**, **Test Failure Diagnosis**, and
**Multi-Agent Validation Coordination** in [AGENTS.md](../../../AGENTS.md) for
evidence reuse, diagnosis, and shared validation ownership. Required phase,
device, CI, and release gates still apply; do not assign each subagent a
duplicate full gate.

When a finding relies on a probe or checker, confirm the relevant comparison

From edonyzpc/personal-assistant, AGPL-3.0.

More from edonyzpc/personal-assistant