portable-identity-document-template-OPEN/skills/PID-update-maintenance-skill.md

---
name: pid-update-maintenance
description: Maintain and update an existing Portable Identity Document (PID) by scanning user-approved local files, emails, transcripts, calendars, databases, exports, and other digital activity over a chosen timeframe. Use this skill when a user wants an AI agent to discover recent accomplishments, learnings, projects, relationships, needs, assets, proof of work, insights, and other signals; draft a reviewable PID update file; incorporate user edits; and append approved updates to the user's PID in Google Docs, Microsoft Word/OneDrive, Markdown, PDF/source file, repository, or another accessible format.
---

# PID Update Maintenance Skill

## Purpose

Help a user keep an existing Portable Identity Document current with minimal manual effort.

People will not manually maintain rich PID profiles indefinitely. Each week they learn things, complete projects, build relationships, create content, solve problems, make decisions, discover tools, attend meetings, and develop new needs or offers that may be valuable signals to others. This skill delegates the ongoing observation, summarization, categorization, and update-drafting work to an AI agent while preserving human review and control.

The agent should look for meaningful change across user-approved sources, draft a local Markdown review file organized by the user's current PID structure, invite the user to edit that draft, learn from those edits when asked, and only then append approved updates to the PID.

## Contract

This skill guarantees:

- It will ask for the user's current PID location and format before attempting updates.
- It will ask which data sources the user authorizes for review.
- It will respect the requested timeframe, defaulting to the last 7 days when no timeframe is provided.
- It will create a local Markdown draft before changing the PID.
- It will organize findings according to the user's actual PID structure when readable, falling back to the standard PID template sections when needed.
- It will distinguish sourced facts, reasonable inferences, and user-review questions.
- It will surface small but meaningful signals, not only major achievements.
- It will preserve privacy and avoid publishing sensitive data unless explicitly approved.
- It will not update, overwrite, publish, email, or share the PID without user confirmation after review.
- It will produce a run receipt documenting inputs, outputs, validations, and unresolved risks.
- It will ratchet lessons from user edits into improved instructions when the user asks the agent to adjust the skill.

## Skill Shape

`system`

This skill coordinates intake, source review, signal extraction, categorization, user review, final PID update, validation, and skill-improvement feedback.

## Requires

This skill requires:

- A user-provided link or path to the current PID.
- User authorization for each source category reviewed.
- A date range or timeframe, or permission to use the default weekly window.
- Ability to read at least one source of recent activity.
- Ability to create a local Markdown draft for review.
- Explicit user approval before modifying the PID.

If the PID is inaccessible, ask the user for an export, local copy, pasted text, or connector access. Do not infer the PID structure from memory alone.

## Ensures

Before finishing, this skill ensures:

- A review draft exists before any PID update.
- The user has either approved the draft, or the PID remains unchanged.
- Approved updates are placed into the correct PID sections.
- Rejected, private, or low-confidence items are excluded or converted into questions.
- The final response clearly states whether the PID was updated or is still awaiting review.

## Capabilities

Required host capabilities:

- CLI tools: useful for local file discovery, date filtering, Git history, and source inventory.
- MCP/connectors: optional but recommended for Gmail, Google Calendar, Google Drive, Google Docs, OneDrive, databases, and other external systems.
- Browser access: optional; use only for user-approved web-accessible PIDs or publication checks.
- Filesystem access: required for local source scanning and Markdown draft output unless the user works entirely through connectors.
- Network access: optional; use only for user-approved cloud documents, repositories, or web sources.
- Subagent support: optional for large source reviews or reviewer-panel passes.
- Document/spreadsheet/PDF support: useful when the PID or sources are Word, Sheets, Excel, PDF, or exported reports.

If a required capability is unavailable, stop or narrow the workflow. Do not pretend to have reviewed inaccessible sources.

## State Scope

`project`

Persistent writes:

- local review draft
- optional source map
- optional open questions file
- optional run receipt
- approved PID update when the user confirms publication

Do not write long-term user memory or update the skill itself unless the user explicitly asks the agent to preserve a recurring preference or adjust the skill.

## Host Primitive Adapter

Map abstract workflow needs to available host actions:

- Ask user: collect PID location, timeframe, source permissions, privacy boundaries, and review approval.
- Read files: inspect only approved local folders and source files.
- Write files: create local Markdown drafts and receipts.
- Run shell commands: list files, inspect modified dates, search text, read Git history, and validate outputs.
- Use connector: read or update Gmail, Calendar, Drive, Docs, Sheets, or other approved systems.
- Use browser: inspect only approved URLs or public PID publication targets.
- Spawn subagent: optional; use for large source reviews or independent privacy/specificity review.
- Create durable report: required; at minimum create or provide the review draft and run receipt.

If the host cannot provide the primitive needed for a requested source or output format, explain the limitation and offer a copy-ready fallback.

## Recommended Intake Checklist

At the beginning, ask the user to provide or confirm the following. Keep the intake concise if the user has already supplied some answers.

```md
# PID Update Intake

## Current PID
- PID location or link:
- PID format: Google Doc / Word / OneDrive / Markdown / PDF / website / repo / other
- Can the agent edit it directly, or should it prepare copy-ready Markdown only?

## Timeframe
- Default: last 7 days
- Requested range:

## Output Location
- Folder for local review draft:
- Preferred draft filename:

## Approved Data Sources
- Local project folders:
- Notes folders:
- Documents folders:
- Downloads or exports:
- Git repositories, including histories:
- Email accounts or labels:
- Calendar events:
- Meeting transcripts or recordings converted to text:
- Chat logs or collaboration tools:
- CRM, database, CSV, JSON, or spreadsheet exports:
- Browser bookmarks or reading lists
- Browser history:
- Social posts, newsletters, or publishing platforms:
- Portfolio, website, or content folders:
- Photos, screenshots, design files, or media metadata:
- Learning logs, courses, books, papers, saved articles:
- Financial, sales, support, product, or analytics exports:
- Other source categories:

## Privacy Boundaries
- Never include:
- Summarize but do not name:
- Ask before including:
- Safe to include:

## Update Goals
- What do you want your PID to become easier to find for?
- What kinds of people, opportunities, or matches matter right now?
- What current needs or offers should be especially visible?
- What should AI systems not misunderstand about you?
```

## Outputs

Primary output:

- `PID-update-review-draft-[YYYY-MM-DD].md`

The draft must be local, reviewable, and organized by PID section.

Secondary outputs when useful:

- `PID-update-source-map-[YYYY-MM-DD].md` mapping each proposed update to source paths, emails, meetings, or other evidence.
- `PID-update-open-questions-[YYYY-MM-DD].md` for uncertain findings that need user answers.
- `PID-update-run-receipt-[YYYY-MM-DD].md` recording what happened.

Final output after approval:

- An updated PID, or copy-ready approved update text when direct editing is unavailable.

## Draft Header Requirement

Every review draft must begin with this instruction block:

```md
# PID Update Review Draft

Agent response to human when PID update review draft is complete:  This is a draft for your review before anything is added to your Portable Identity Document (PID).

Please edit freely:
- delete anything that should not be included
- correct anything inaccurate
- add missing context, links, examples, names, or proof
- mark private items that should be removed or generalized
- strengthen anything that feels too vague or too narrow

After you edit this draft, ask the agent to continue from your revised file and update your PID.

If your edits reveal a recurring preference, missing category, privacy rule, source type, or better way to describe your work, ask the agent to adjust the PID update maintenance skill so future runs improve.
```

## PID Section Mapping

First read the user's current PID and infer its headings. Preserve the user's structure when appending updates.

If the PID cannot be read or has no clear structure, use the standard PID sections:

- Open To
- What I Have
- What I Need
- Current Focus
- Interests, Passions, Talents
- History
- Credibility
- Identity Layer
- Proof Of Work
- Additional Signals
- Match Context
- Update Log

This list is based on the pid-template.md file.  That file may evolve to a different structure.  Make sure the user has given the AI access to the latest version of this file.  

## Source Categories To Review

When authorized, inspect sources for signals in these categories:

- Local files: documents, notes, working drafts, folders created or modified, exports, PDFs, spreadsheets, presentations.
- Project work: repos, commits, issue notes, task files, plans, specs, prototypes, designs, scripts, data pipelines.
- Email: sent mail, received threads, introductions, decisions, requests, collaborations, follow-ups, newsletters, opportunities.
- Calendar: meetings, events, travel, conferences, workshops, recurring commitments, relationship-building activity.
- Meeting records: transcripts, summaries, action items, decisions, objections, insights, stakeholder names.
- Chats and collaboration tools: Slack, Teams, Discord, SMS exports, comments, shared docs, decision trails.
- Databases and structured exports: CSV, JSON, SQL exports, CRM, support tickets, sales, analytics, product usage, research datasets, MCP connectors.
- Content and publishing: articles, social posts, newsletters, videos, podcasts, talks, comments, drafts, outlines.
- Learning and research: courses, books, papers, saved articles, annotations, experiments, reading notes, aha moments.
- Creative and design work: images, decks, sketches, mockups, media files, design artifacts.
- Relationships and network: new collaborators, advisors, customers, vendors, communities, referrals, introductions made or received.
- Proof and credibility: certifications, testimonials, awards, media mentions, event participation, shipped artifacts, measurable outcomes.
- Needs and constraints: blockers, missing resources, requested help, tools needed, funding needs, hiring needs, feedback needs.
- Assets and offers: reusable systems, templates, data, content, capabilities, tools, access, audiences, products, services.
- Identity signals: values clarified, principles tested, preferred work patterns, strengths, weaknesses, energy patterns.
- Match context: ideal collaborators, non-ideal matches, emerging opportunities, who needs what the user has, what the user needs from others.

## Signal Extraction Heuristics

Be thorough. Small discoveries matter.

Look for:

- created, edited, shipped, published, launched, fixed, automated, cleaned, migrated, organized, analyzed
- learned, realized, discovered, reframed, decided, validated, invalidated, changed mind
- met, introduced, advised, helped, asked, offered, followed up, partnered
- researched, compared, evaluated, recommended, rejected, adopted, stopped using
- wrote, recorded, presented, designed, prototyped, tested, documented
- solved, debugged, unblocked, improved, simplified, clarified
- evidence of recurring interests, emerging vocabulary, named systems, new frameworks, and repeated themes
- needs implied by blockers, unanswered questions, stalled work, repeated friction, missing expertise, missing access
- offers implied by artifacts, repeated help given, reusable methods, strong opinions, unique data, relationships, domain experience

Prefer concrete, grounded language over generic praise.

## Workflow

### Phase 1: Intake And Permission

1. Ask for the current PID path/link and format.
2. Ask for the timeframe. Use the last 7 days if the user says weekly or gives no range.
3. Ask which source categories are approved and where to find them.
4. Ask for privacy boundaries.
5. Ask where to save the local review draft.

Stop if the user has not authorized any source review.

### Phase 2: Read The Current PID

1. Read the PID from the provided location or connector.
2. Identify headings, section order, tone, and current emphasis.
3. Identify stale sections, thin sections, repeated vocabulary, open needs, existing offers, and match context.
4. Note the PID's publication target and any format constraints.

Completion criteria:

- PID structure is known, or fallback structure is selected.
- PID privacy posture is understood.

### Phase 3: Source Inventory

1. List each approved source.
2. Record access method, date range, and scan limits.
3. Prefer metadata and targeted searches before reading large corpora.
4. Do not read sources outside the user's approved categories.
5. Track unreadable or skipped sources in the run receipt.

Completion criteria:

- Reviewed sources are explicit.
- Skipped sources are explicit.

### Phase 4: Extract Candidate Signals

Create raw notes with source references for:

- accomplishments
- projects advanced or completed
- problems solved
- decisions made
- ideas, insights, and aha moments
- learnings and recommendations
- relationships and introductions
- content created or published
- tools, systems, templates, datasets, or assets created
- proof of work and credibility signals
- emerging needs, blockers, constraints, and asks
- changed priorities or current focus
- match opportunities: who may need what the user has, and who may have what the user needs

Mark each candidate as:

- `Fact` when directly supported by a source.
- `Inference` when reasoned from evidence.
- `Question` when user confirmation is needed.

### Phase 5: Categorize By PID Structure

Map candidate signals to the user's PID sections.

Rules:

- Put time-bound activity in Update Log.
- Put reusable capabilities, systems, assets, data, tools, products, and relationships in What I Have.
- Put blockers, asks, desired collaborators, resources, capital, access, feedback, or support in What I Need.
- Put active projects, experiments, research, and initiatives in Current Focus.
- Put durable interests, curiosities, domains, and recurring questions in Interests, Passions, Talents.
- Put shipped artifacts, case studies, builds, results, and evidence in Proof Of Work.
- Put endorsements, certifications, events, media, publications, and platform presence in Credibility.
- Put values, principles, strengths, weaknesses, work style, and energy patterns in Identity Layer.
- Put ideal collaborators, ideal problems, non-ideal matches, and matching guidance in Match Context.
- Put observations, frameworks, recommendations, predictions, writing samples, questions, and applied knowledge in Additional Signals.

Allow the same discovery to appear in more than one section only when each placement adds distinct value.

### Phase 6: Draft The Review File

Write `PID-update-review-draft-[YYYY-MM-DD].md`.

For each section, include:

- proposed additions
- source/evidence note
- confidence level
- privacy note if relevant
- user-review questions

Suggested item format:

```md
## [PID Section]

### Proposed Addition
- [Fact / Inference / Question] Proposed PID text.
  - Evidence: [source path, email/thread, meeting title/date, export row, or note]
  - Confidence: High / Medium / Low
  - Privacy: Safe / Review / Generalize / Exclude unless approved
```

End the draft with:

- `Possible Things Others May Need From You`
- `Possible People Or Opportunities You May Need`
- `Open Questions For You`
- `Suggested Skill Improvements Based On This Run`

### Phase 7: User Review Gate

Stop after creating the draft.

Ask the user to review and edit the Markdown file. Do not update the PID yet.

Continue only when the user explicitly says the draft is ready, approved, or provides the revised file.

### Phase 8: Incorporate User Edits

1. Read the edited review draft.
2. Treat user edits as authoritative.
3. Remove rejected items.
4. Generalize private items.
5. Strengthen items the user expanded.
6. Identify any preference that should improve future skill runs.

If the user's edits imply a recurring rule, ask whether to update the skill or add that rule to a local preference note.

### Phase 9: Update The PID

Update method depends on format:

- Google Doc: use the Google Drive/Docs connector when available, or prepare copy-ready Markdown.
- Microsoft Word/OneDrive: edit a local `.docx` or prepare copy-ready content for OneDrive when direct connector access is unavailable.
- Markdown: append or merge directly into the appropriate sections.
- PDF: update the source document first when possible; avoid editing the PDF as the canonical source unless the user confirms it is the source of truth.
- Website/repo: update the source Markdown/data files, not only the generated site.
- Unknown or locked format: provide copy-ready approved update text.

Append to existing sections rather than rewriting the entire PID unless the user requests restructuring.

### Phase 10: Validate And Receipt

Before finishing:

1. Re-read the changed PID when possible.
2. Confirm approved updates appear in the intended sections.
3. Confirm rejected/private items were not included.
4. Confirm the Update Log includes the timeframe and date.
5. Confirm no unsupported inference was promoted to fact.
6. Write or update the run receipt.

## Validation

Structural validation:

- [ ] Current PID was read or fallback limitation was disclosed.
- [ ] Review draft was created before PID update.
- [ ] Draft used the user's PID structure or standard fallback.
- [ ] Every proposed update has section placement.
- [ ] Final PID update only happened after user approval.

Evidence validation:

- [ ] Every fact has source evidence.
- [ ] Every inference is labeled.
- [ ] Every low-confidence item is either excluded or turned into a question.
- [ ] Source limits and skipped sources are recorded.

Privacy validation:

- [ ] Privacy boundaries were collected.
- [ ] Sensitive identifiers were excluded or generalized.
- [ ] Private client, employer, family, health, legal, financial, or confidential project details were not published without approval.
- [ ] Draft includes privacy notes where needed.

Quality validation:

- [ ] Small learnings, improvements, and aha moments were considered.
- [ ] Needs and offers were both reviewed.
- [ ] Possible match implications were surfaced.
- [ ] Generic language was replaced with concrete signals where possible.
- [ ] User edits were incorporated faithfully.

## Test Surface

This skill can be tested through:

- Static checks: required sections exist in the draft; draft header exists; run receipt exists.
- Invariant checks: no PID update before review approval; every proposed fact has evidence; every inference is labeled.
- Fixture tests: weekly local folder scan; email-only scan; meeting-transcript scan; sparse-source scan; large-folder scan; private-client scan; edited-draft continuation.
- Behavioral tests: agent asks for PID location, source authorization, timeframe, privacy boundaries, and review approval.
- LLM-as-judge evals: whether extracted updates are useful, specific, grounded, privacy-aware, and mapped to PID sections.

## Edge Cases

Actively handle:

- user has no current PID or provides an inaccessible PID
- PID is a PDF with no editable source
- user approves many folders but no date range
- file modified time is misleading because old files were copied
- many files changed but few contain meaningful identity signals
- email threads contain sensitive personal or business information
- meeting transcripts include other people's private statements
- source materials contradict the existing PID
- user edits the draft heavily
- user wants direct publishing but connector access is unavailable
- user's PID structure differs from the standard template
- the same update belongs to multiple sections
- findings are valuable but too speculative
- the agent discovers needs the user did not explicitly state
- the agent discovers offers the user is undervaluing

## Ratchet Rules

When user edits, validation failures, or review discussions reveal a recurring issue, convert it into a durable improvement.

Possible ratchet artifacts:

- update this skill's instructions
- add a privacy rule
- add a new source category to the intake checklist
- add a recurring user preference
- add an anti-pattern
- add a validation checklist item
- add a fixture scenario
- add a stronger section-mapping rule
- add a local source inventory template

Examples:

- If the user repeatedly deletes a type of personal information, add it to privacy boundaries for future runs.
- If the agent misses a recurring source such as meeting transcripts, add that source category.
- If the user rewrites vague accomplishments into measurable proof, add a specificity rule.
- If the agent overemphasizes major projects and misses small learnings, strengthen the small-signal extraction heuristic.
- If the agent puts needs in Update Log only, add a rule to also consider What I Need and Match Context.

Do not merely correct the current PID update. Make future runs better.

## Anti-Patterns

Do not:

- update the PID before the user reviews the Markdown draft
- scan sources the user did not authorize
- treat all recent files as meaningful
- dump raw private notes into the PID
- publish sensitive details because they were found in a source
- invent accomplishments, relationships, needs, or proof
- hide uncertainty
- collapse the update into a resume-style summary
- ignore small learnings, aha moments, process improvements, or recommendations
- only capture what the user explicitly says they need; infer possible needs and ask for confirmation
- only capture what the user explicitly says they offer; infer possible offers and ask for confirmation
- overwrite the whole PID when an append would preserve user control
- treat PDF editing as canonical when a source document exists
- treat user edits as optional suggestions

## Run Receipt

Create a receipt in the final response or in `PID-update-run-receipt-[YYYY-MM-DD].md`:

```md
# PID Update Run Receipt

## Timeframe

## PID Source

## Approved Sources Reviewed

## Sources Skipped Or Unavailable

## Draft Created

## User Review Status

## PID Update Status

## Validation Results

## Privacy Decisions

## Notable Inferences

## Open Questions

## Skill Ratchet Suggestions
```

## Final Report

When finished, report concisely:

- where the review draft was created
- what sources and timeframe were reviewed
- whether the PID was updated or is awaiting review
- what validations passed
- what risks or open questions remain
- any suggested skill improvements learned from the run

## Suggested User Prompt

```text

Use the PID Update Maintenance Skill to update my Portable Identity Document.

My PID is here: [path or link]
Review this timeframe: [last 7 days / dates]
Save the review draft here: [folder]

Approved sources:
- [folders]
- [email labels or accounts]
- [calendar range]
- [meeting transcript folders]
- [CSV/JSON/database exports]
- [other sources]

Privacy boundaries:
- never include [items]
- generalize [items]
- ask before including [items]

First create a local Markdown review draft organized by my PID sections. Do not update the PID until I review and approve the draft.
```

## One-Sentence Version

Scan user-approved recent activity, extract grounded identity signals, draft them into the user's PID structure for human review, then append approved updates so the PID stays fresh, specific, and useful for AI-native matching.