---
name: update-academic-records
description: Use when a user reports a new award, abstract, talk, teaching session, grant, appointment, certification, membership, service role, mentoring activity, project or education/training update, or a media appearance or coverage item for their existing academic website YAML records, or adds, defers or replaces a PDF, poster or PowerPoint attachment to an existing activity.
---

Start by following [profile discovery and resumable setup](../../references/preferences.md). For missing or incomplete preferences in an existing records project, use [configure-academic-records](../configure-academic-records/SKILL.md). Use [initialize-academic-records](../initialize-academic-records/SKILL.md) only for requested first-time CV/site setup or initial source reconciliation. A missing profile alone does not authorize a new project, a repeated CV import or a second profile. Reuse confirmed answers. If the intended starting point is unclear, ask one focused question before choosing a workflow. Inaccessible or corrupt existing state requires access/reviewed recovery, not replacement; missing file permissions require the handoff/access workflow, not initialization.

For postponements, follow [structured deferrals](../../references/deferrals.md). Save the user's actual revisit date/time or exact named trigger, suppress questions through questions_to_ask until eligible, record one actual offer and avoid later-cycle repeats. User resumption/rescheduling is explicit; terminal items stay closed. Honor legacy prose deferrals until separately approved migration; do not silently rewrite pending state or invent a trigger date.

For new YAML/PDF saves, read [approval evidence](../../references/approval-evidence.md). After actual approval of the displayed exact proposal, record the minimal quoted response, real chat/proposal references and known message time (or explicitly unavailable time), then supply --approval-evidence FILE. Bind it to the exact ID/hash/destination; PDF approval must explicitly cover public use. Do not fabricate quotes or metadata, silently backfill older receipts, or treat agent-supplied evidence as independent authentication. This changes audit requirements, not permission scope.

For routine saves use [packaged commands and consumer-inspection reuse](../../references/routine-save.md). Prefer approved_save.py for one approved YAML proposal: provide actual response context with the explicitly approved ID/hash/destination, let it capture the real recording time and delegate to proposals.py apply. Do not write a custom Python wrapper for this sequence. The direct apply command remains supported when a complete valid evidence file already exists. Reuse a run-local consumer assessment only after checking unchanged hashes, fields, dependencies and instructions; never cache helper validation or skip required checks. No-change answers use the existing confirmation batching workflow.


Read [question interaction](../../references/questions.md) before asking the user anything. Ask one question at a time through the host's structured question capability when available, with a single chat question as fallback.

For YAML approval, show the helper-generated diff.txt or a faithful readable excerpt of that exact diff, with its proposal ID and validation. Label omissions; do not substitute an independently reconstructed change that could differ from the staged bytes. Diff generation preserves original/candidate line endings and writes UTF-8 without platform newline translation. Preserve historical diff files/receipts; this correction affects newly generated proposals only.

Prepare proposed changes to existing authoritative records when authorized file access is available. **Every record change requires explicit user approval of the concrete proposal before saving**, including conversational requests. Reporting a new activity is not approval of unseen YAML. Silence never counts as approval. Read [project boundaries](../../references/project.md) and [runtime discovery](../../references/runtime.md) first. This plugin supplies instructions and validation, not filesystem privileges or an MCP storage service. Never claim installation grants access, or that this plugin enforces a filesystem sandbox.

Before setup or filesystem commands, check whether this chat has the required authorized local tools. If record/resource access is missing, follow [handoff-academic-update](../handoff-academic-update/SKILL.md): collect facts and prepare a request, forward only with human authorization when tools/configuration permit, otherwise provide the manual fallback. Do not attempt full setup or create a project to bypass missing access. In the configured destination chat, resume normal maintenance and recheck access.

1. Read [setup and pending work](../../references/setup.md). Prefill setup from known confirmations and ask only unresolved questions. Resume pending items before repeating questions. Read applicable project instructions and current files. Current direct user instructions supersede historical restrictions. Confirm the actual root and permissions; a path alone is not authorization. Run `proposals.py inspect DATA` read-only and explain whether the 13-file adapter matches the existing layout. File presence alone is not content/consumer compatibility: validate baseline and inspect consumers next. If unsupported, show missing/incompatible files and a concrete suggested adapter/consumer change report for the owner's site maintainer, then stop incompatible writes. Never create empty YAML to bypass the check. Do not redo CV import or parse generated CVs. Read relevant website and CV consumers without executing them.
2. For teaching, abstracts and presentations, including attachment-only follow-ups, read [attachments](../../references/attachments.md) and its mandatory [privacy warning](../../references/privacy.md). Prompt for a PDF/PowerPoint now, later or none unless already answered. Explicitly warn immediately on suspected patient identifiers and pause that file's saving/linking until resolved. Support the separate approved resource-folder scope without expanding YAML or parent-source permissions. Convert PPT/PPTX to PDF using an available local converter, inspect the result and propose its path with the YAML diff. Deferred uploads stay private and later attach to the same record, never a duplicate.

   Identify the activity type and search existing records before adding anything. A new award associated with an existing abstract normally belongs in its existing award field. Avoid creating another authoritative copy of the same activity. Preserve shared appointments and mentee relationships.
3. Collect only missing facts needed by the schema and consumers. Ask one focused question at a time, choosing the next missing fact needed to proceed: title, institution or meeting, role, date at known precision, authors in exact order, presentation type or mentees where applicable. Do not infer authors, dates, institutions, awards, active status or planned appointment completion. Preserve unknown optional fields as null where compatible. If a required full date is unknown, hold that record pending rather than inventing a date. Save an incomplete candidate and focused questions in private state; tell the user what is missing. Do not create a live placeholder. Optional missing attachments can remain null; never link a nonexistent file.
4. Read the current schema and preserve field types, comments, quoting, unrelated records and record order. Use minimal textual edits rather than serializing the entire file. Preserve resource paths, case, citation keys, enum spelling and links. Scalar author strings stay scalar. Teaching sessions stay a dates list. New IDs are unique only in files already using IDs; do not introduce a migration implicitly.
5. Use helper-managed snapshots and backups. `propose` stages and hashes the complete supported source snapshot; `apply` creates a unique hash-verified backup of its target inside the private proposal directory before writing, rechecks sources and verifies saved bytes. Do not create duplicate manual copies or a second staging tree merely to repeat those safeguards. If actual project instructions require an additional run-level backup or other safeguard, follow that explicit requirement once in authorized storage and report it separately. Preserve all earlier backups and failure evidence. Never bypass a helper blocker with an ad-hoc write.
6. Inspect the actual website/CV consumers for changed fields and separately check resource links and facts; these remain assistant responsibilities. Use the helper's full-snapshot R validation through `propose` and `apply`, with the configured runtime/library, rather than separately running the same validator against unchanged inputs. The helper stages required YAML, optional media when present, and only the profile-configured bibliography for reference checks. Review baseline/candidate warnings plus error_review resolved/remaining errors before exact approval. New/changed errors and parser/structure failures block; retained errors stay bound to unchanged record content and counted occurrences under verification.md. Do not call the dataset error-free when inherited errors remain or silently repair unrelated records. If R/yaml or the helper is unavailable, a safe parser may support a read-only assessment, but hold saving pending until the required helper validation can run. Do not install dependencies without authorization.
7. Use `scripts/proposals.py propose STATE DATA FILE CANDIDATE RSCRIPT` to stage a single-file change, validate the full snapshot, save source hashes, and generate the exact diff. Add `--r-library PATH` when needed. Show a readable before/after proposal, source, missing facts, validation and proposal ID. STOP before any live write and request approval. Record the actual user response privately. Only after explicit approval of that proposal, call `scripts/proposals.py apply STATE ID --approval ID --approval-evidence FILE RSCRIPT`. Never manufacture approval or invoke apply merely because the initial request said 'add'. The helper checks the allowlist, stale sources and changed staged content and creates a verified backup. Changed facts, diff or source invalidate approval and require a new proposal. For multiple files, obtain approval for the entire named set and refresh proposals when earlier writes change the baseline. Apply the minimal approved change only to profile-approved YAML. Review the saved diff and the helper receipt/status, including actual backup and validation evidence; use its verified snapshot/hash checks rather than duplicating the same validation pass. Perform any separate consumer/resource checks required by the change or project instructions. Attachment placement may use the separately approved resource-folder workflow. Do not render, run R/cv.R, commit, publish, edit Zotero/BibTeX or parent sources. If compatibility requires a parent change or new file/schema, explain precise suggested edits for the user and hold the incompatible data change.
8. Run `status STATE ID` or `list STATE` after any interrupted apply before deciding what happened. Outcomes distinguish awaiting_approval, stale, failed_before_write, saved_unverified, verified_saved, changed_after_save and conflict. Never call saved_unverified 'not saved' or blindly retry; show actual current status, backup and a recovery proposal. For failed_before_write, the same proposal cannot be reapplied: inspect status, backup and the failure cause, preserve all evidence, resolve the cause, then create a fresh proposal from current sources and obtain new exact approval even if the diff is identical. Never reuse the old approval or delete attempt/backup files to reset status. For saved_unverified, review verification recovery without rewriting. No automatic rollback. For pending work, use `event STATE PENDING_ID EVENT_JSON` to record answers/status/proposal links and `list STATE` to reopen effective state. Report records changed, facts and source used, validation, backup location and unresolved questions. Finish with the tailored [owner handoff](../../references/owner-handoff.md): say exactly what source was saved and which website/CV outputs remain pending, using inspected project commands and the saved rendering preference. Routine supported updates need no R/Quarto source edits. Separate saved updates from pending proposals. Approval is mandatory even for routine updates. The helper's approval argument is an operator assertion, not human authentication: the assistant must obtain actual user approval. A test-fixture approval never authorizes real record changes.

Publications: when the confirmed publication store is Zotero, route additions and metadata-correction requests to [update-zotero-records](../update-zotero-records/SKILL.md). This is a separate approval-gated library workflow, not permission to edit BibTeX, YAML publications, consumer files or outputs. Other stores remain proposals until a supported authorized integration exists. Media uses the profile's approved destination. For an existing authorized media.yml, follow [media records](../../references/media.md); it is optional and does not change the 13 required files. New-file migrations require a coordinated approved schema/consumer plan; never infer media permission from installation.


For save/recovery interpretation, follow [verification](../../references/verification.md). Recheck current scope before recovery, distinguish historical receipts from current snapshot drift, and never describe a saved-but-unverified target as an unapplied proposal.

Bibliography auto-exports alone do not invalidate exact YAML approval: the helper revalidates against the current bibliography before and after saving, with bounded retries for concurrent exports. Any changed validation warnings require renewed review. Show both warning sets and obtain approval of a fresh proposal before writing; after a write, report saved_unverified and reconcile without blindly retrying or rewriting records. Bibliography configuration changes and changed YAML/staged bytes still require reconciliation. Follow the detailed receipt and recovery rules in verification.md.

For check-ins, follow [check-in message and guided update conversation](../../references/check-in.md). Present source-derived suggestions first, then verified CV/site viewing links and linked categories for assistant-guided submissions. Setup must include that flow in tasks it creates. Respect regular-reminder preference and Nothing to add without repeated same-cycle nudges; host UI limitations require honest link/chat fallback.

After a verified source save, resolve the saved output assistance through [output follow-through](../../references/output-execution.md). Routine record helper scope remains unchanged; separate output stages run only when explicitly authorized and supported. Owner-managed modes use the existing manual handoff. The same preferences govern tasks; public-CV scope is separate.