From 1530b829efaa5d1bc859b9f528e2405887bdcec0 Mon Sep 17 00:00:00 2001 From: eddiesoehnel Date: Tue, 16 Jun 2026 07:39:24 -0600 Subject: [PATCH] added --- skills/PID-initial-creation-skill.md | 237 +++++++++++++++++++++++- skills/PID-update-maintenance-skill.md | 239 ++++++++++++++++++++++++- 2 files changed, 466 insertions(+), 10 deletions(-) diff --git a/skills/PID-initial-creation-skill.md b/skills/PID-initial-creation-skill.md index c571e63..62c45f3 100644 --- a/skills/PID-initial-creation-skill.md +++ b/skills/PID-initial-creation-skill.md @@ -1,16 +1,19 @@ --- name: pid-initial-creation description: Create a person's initial Portable Identity Document (PID) from gathered source materials using the PID template structure. Use this skill when a user wants to generate a first PID from resumes, LinkedIn profiles, bios, project notes, personality tests, websites, social posts, portfolio materials, or other reference documents. -version: 1.0 -status: draft -intended_hosts: +--- + +# PID Initial Creation Skill + +## Compatibility Notes + +- Version: 1.0 +- Status: draft +- Intended hosts: - Claude Desktop - Codex Desktop - ChatGPT with file/context access - other local or cloud AI agent apps ---- - -# PID Initial Creation Skill ## Purpose @@ -140,6 +143,7 @@ If the user requests structured data or the host supports writing multiple files - `PID-source-map.md` — maps PID claims back to source materials - `PID-open-questions.md` — questions the user should answer before publishing - `PID-publication-notes.md` — guidance for publishing via Google Drive, OneDrive, GitHub, PDF, or personal website +- `PID-creation-run-receipt.md` — durable audit record of inputs, assumptions, outputs, validations, changes, privacy decisions, and unresolved risks --- @@ -178,6 +182,8 @@ Before finishing, this skill ensures: - the PID contains concrete capabilities, assets, needs, proof, and match context - the output is organized for AI comprehension and human review - the final answer tells the user what was produced and what still needs review +- a durable run receipt is created for serious PID creation workflows +- the final response summarizes the receipt but does not replace it --- @@ -717,6 +723,57 @@ This list is based on the pid-template.md file. That file may evolve to a diffe - [ ] Proof links or artifact prompts are included where needed. - [ ] The document is suitable for future conversion into repo structure or JSON. +## Receipt Validation + +- [ ] Receipt names the skill and source/version context. +- [ ] Receipt lists all inputs used. +- [ ] Receipt lists assumptions made. +- [ ] Receipt lists capabilities used. +- [ ] Receipt lists outputs created. +- [ ] Receipt lists validations run. +- [ ] Receipt records skipped or unavailable inputs. +- [ ] Receipt records privacy decisions. +- [ ] Receipt records unsupported claims removed or flagged. +- [ ] Receipt records unresolved risks and next steps. + +--- + +# Validation Tiers + +Use validation tiers so the agent does not confuse a quick structural check with full quality review. + +## Tier 1: Fast Deterministic Checks + +Run every time: + +- required PID sections exist +- required output files exist or are provided in the response +- intentional review prompts are clearly marked +- no obvious unresolved placeholders remain except `[USER ...]` prompts +- no sensitive identifiers are included without explicit approval +- the run receipt exists for serious workflows + +## Tier 2: Realistic Workflow Review + +Run for important PID drafts, complex source sets, or user-facing deliverables: + +- compare draft claims against source materials +- review privacy-sensitive sections manually or with a reviewer pass +- verify the review checklist points to concrete user actions +- verify publication notes match the user's intended format +- confirm the run receipt can be used by a future agent to resume or audit the work + +## Tier 3: LLM-As-Judge Or Reviewer Panel + +Use when quality is subjective: + +- authenticity +- specificity +- usefulness for AI matching +- clarity +- faithfulness to sources +- whether the PID sounds like the user rather than generic internet language + --- # Test Surface @@ -760,6 +817,36 @@ This skill can be tested through: --- +# Coverage And Edge-Case Audit + +Before finishing a serious PID creation run, map the workflow coverage: + +- source types reviewed +- source types skipped or unavailable +- PID sections completed +- PID sections weak or missing +- privacy-sensitive areas reviewed +- unsupported or low-confidence claims +- publication-readiness gaps +- future-maintenance gaps + +Mark each uncovered gap as: + +- `[MANUAL]` user should review or answer +- `[EVAL]` quality judgment needed +- `[PRIVACY]` approval or generalization needed +- `[SOURCE]` missing or unreadable source material +- `[FUTURE]` good candidate for later PID maturity work + +For every meaningful gap, either: + +1. add it to `PID-review-checklist.md` +2. add it to `PID-open-questions.md` +3. record it in the run receipt +4. ask the user before proceeding if the gap blocks a faithful draft + +--- + # Edge Cases Actively handle: @@ -787,6 +874,34 @@ Actively handle: --- +# Regression Rule + +If this skill discovers that something previously worked and now breaks, create a regression artifact immediately. + +Do not merely fix the current output. + +Acceptable regression artifacts: + +- updated skill instruction +- validation checklist item +- fixture scenario +- example prompt +- anti-pattern +- privacy rule +- reviewer-panel rule +- source-material intake question +- output schema requirement +- STOP gate + +Examples: + +- If the agent fails to create a review checklist, add an explicit checklist validation item. +- If the agent invents claims from sparse materials, add a stronger source-grounding rule. +- If a privacy-sensitive item slips through, add a privacy checklist rule and edge case. +- If a final response omits the durable receipt, add receipt validation and final-report guidance. + +--- + # Ratchet Rules When this skill discovers a recurring mistake, ambiguous case, failed validation, or agent shortcut, convert the lesson into at least one durable artifact: @@ -840,34 +955,140 @@ Do not: --- +# Skill Freshness And Inventory + +When this skill is updated, verify: + +- frontmatter contains only `name` and `description` +- compatibility notes in the body still match intended hosts +- PID section lists still match `PID-template.md` +- output filenames still match the README and user prompts +- validation sections still require privacy, faithfulness, specificity, AI usability, and receipt checks +- receipt requirements still match the current ratchet-based skill framework +- no private/local-only maintainer paths are required for normal user operation +- suggested prompts still mention the current skill and template names + +If `PID-template.md` changes, update the section mapping and structural validation in this skill. + +--- + # Run Receipt -For serious use, leave a short run receipt at the end of the final response or in a separate file: +For serious use, leave a durable, inspectable receipt. Treat the receipt as the replay/audit record for the skill run, not merely a human-readable final summary. + +The receipt should let a future agent answer: + +- what skill ran +- under what version/context it ran +- inputs used +- assumptions made +- capabilities used +- tool calls or commands executed +- external state changed +- outputs produced +- validations run +- failures found +- fixes applied +- ratchet artifacts added or suggested +- unresolved risks +- follow-up recommendations +- how the run could be resumed, audited, forked, or repeated + +If the receipt is compacted into a final response, preserve the full receipt as a file, JSON artifact, test log, or run directory whenever the workflow is important. A final-response summary is a projection of the receipt; it is not the receipt itself. + +Use this Markdown structure when writing `PID-creation-run-receipt.md`: ```md # PID Creation Run Receipt +## Skill Run + +- Skill name: +- Skill source/path: +- Skill version or file timestamp if known: +- Run date: +- Executor/host: +- User request: + ## Inputs Used +- PID template: +- Source materials: +- User-provided answers: +- Privacy rules: +- Customization goals: +- Publication target: + +## Assumptions Made + +## Capabilities Used + +- Filesystem: +- Connectors: +- Browser/network: +- Subagents: +- Document/PDF/spreadsheet tools: + +## Tool Calls Or Commands Executed + +## External State Changed + +- Files created: +- Files modified: +- Cloud documents modified: +- Nothing changed without explicit user approval: + ## Outputs Produced +- PID draft: +- Review checklist: +- Source map: +- Open questions: +- Publication notes: +- Run receipt: + ## Sections Completed ## Sections Needing User Review ## Privacy Checks Performed +## Sensitive Items Removed Or Generalized + ## Unsupported Claims Removed Or Flagged ## Validation Results +## Failures Or Gaps Found + +## Fixes Applied + ## Ratchet Lessons +## Ratchet Artifacts Added Or Suggested + +## Unresolved Risks + +## Resume / Audit Notes + +- How a future agent can continue: +- What should be reviewed first: + ## Recommended Next Steps ``` --- +# Receipt Vs Final Report + +The final report is for the user. + +The run receipt is for future agents, auditors, and maintainers. + +Do not rely on the final response as the only record when files were created, source materials were interpreted, validations were run, validations were skipped, privacy decisions were made, failures were discovered, or ratchet artifacts were added or suggested. + +--- + # Final Report When finished, report: @@ -877,8 +1098,10 @@ When finished, report: - what was validated - what still needs user review - whether any sensitive material was removed or flagged +- where the run receipt was written, or why it was not written - where the user should publish the PID - what optional next-level upgrades are recommended +- what ratchet artifact was added or suggested if the run exposed a recurring issue Keep the final report concise unless the user asks for detail. diff --git a/skills/PID-update-maintenance-skill.md b/skills/PID-update-maintenance-skill.md index e8453a5..e7f473b 100644 --- a/skills/PID-update-maintenance-skill.md +++ b/skills/PID-update-maintenance-skill.md @@ -57,6 +57,8 @@ Before finishing, this skill ensures: - 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. +- A durable run receipt is created for serious PID update workflows. +- The final response summarizes the receipt but does not replace it. ## Capabilities @@ -166,7 +168,7 @@ 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. +- `PID-update-run-receipt-[YYYY-MM-DD].md` durable audit record of inputs, assumptions, source boundaries, outputs, validations, changes, privacy decisions, and unresolved risks. Final output after approval: @@ -439,6 +441,59 @@ Quality validation: - [ ] Generic language was replaced with concrete signals where possible. - [ ] User edits were incorporated faithfully. +Receipt validation: + +- [ ] Receipt names the skill and source/version context. +- [ ] Receipt lists the timeframe reviewed. +- [ ] Receipt lists all inputs and source categories used. +- [ ] Receipt lists assumptions made. +- [ ] Receipt lists capabilities used. +- [ ] Receipt lists outputs created. +- [ ] Receipt lists validations run. +- [ ] Receipt records skipped, unavailable, or unauthorized sources. +- [ ] Receipt records whether the PID was changed or left unchanged. +- [ ] Receipt records privacy decisions. +- [ ] Receipt records unsupported inferences removed, downgraded, or turned into questions. +- [ ] Receipt records unresolved risks and next steps. + +## Validation Tiers + +Use validation tiers so the agent does not confuse a quick structural check with full quality review. + +### Tier 1: Fast Deterministic Checks + +Run every time: + +- intake captured PID location, timeframe, approved sources, and privacy boundaries +- review draft exists before any PID update +- every proposed update has a PID section placement +- every fact has evidence +- every inference is labeled +- rejected/private items are excluded from final PID updates +- the run receipt exists for serious workflows + +### Tier 2: Realistic Workflow Review + +Run for important PID updates, large source sets, or direct publication: + +- compare proposed additions against evidence +- verify source boundaries were respected +- verify the user review gate was honored +- re-read the updated PID when possible +- confirm approved updates appear in intended sections +- confirm the run receipt can be used by a future agent to resume or audit the work + +### Tier 3: LLM-As-Judge Or Reviewer Panel + +Use when quality is subjective: + +- usefulness of extracted signals +- specificity of additions +- privacy judgment +- match-context reasoning +- whether inferred needs/offers are plausible and clearly labeled +- whether small learnings and accomplishments were surfaced without noise + ## Test Surface This skill can be tested through: @@ -449,6 +504,38 @@ This skill can be tested through: - 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. +## Coverage And Edge-Case Audit + +Before finishing a serious PID update run, map the workflow coverage: + +- approved source categories reviewed +- approved source categories skipped or unavailable +- source categories intentionally not authorized +- date/timeframe coverage +- PID sections with proposed updates +- PID sections with no useful changes +- privacy-sensitive items reviewed +- unsupported or low-confidence inferences +- user edits incorporated +- direct PID update status +- future-maintenance gaps + +Mark each uncovered gap as: + +- `[MANUAL]` user should review or answer +- `[EVAL]` quality judgment needed +- `[PRIVACY]` approval or generalization needed +- `[SOURCE]` missing, unreadable, or unauthorized source material +- `[CONNECTOR]` connector or edit capability unavailable +- `[FUTURE]` good candidate for skill improvement or later PID maturity work + +For every meaningful gap, either: + +1. add it to the review draft +2. add it to the open questions file +3. record it in the run receipt +4. ask the user before proceeding if the gap blocks a faithful update + ## Edge Cases Actively handle: @@ -469,6 +556,33 @@ Actively handle: - the agent discovers needs the user did not explicitly state - the agent discovers offers the user is undervaluing +## Regression Rule + +If this skill discovers that something previously worked and now breaks, create a regression artifact immediately. + +Do not merely fix the current output. + +Acceptable regression artifacts: + +- updated skill instruction +- validation checklist item +- fixture scenario +- example prompt +- anti-pattern +- privacy rule +- source category intake rule +- section-mapping rule +- output schema requirement +- STOP gate + +Examples: + +- If the agent updates a PID before user review, add a stronger STOP gate and behavioral test. +- If the agent scans unauthorized sources, add a source-boundary validation item. +- If private information slips into an approved update, add a privacy edge case and checklist rule. +- If the agent misses small learnings and only captures major achievements, strengthen signal extraction heuristics. +- If the final response omits the durable receipt, add receipt validation and final-report guidance. + ## Ratchet Rules When user edits, validation failures, or review discussions reveal a recurring issue, convert it into a durable improvement. @@ -514,38 +628,155 @@ Do not: - treat PDF editing as canonical when a source document exists - treat user edits as optional suggestions +## Skill Freshness And Inventory + +When this skill is updated, verify: + +- frontmatter contains only `name` and `description` +- PID section lists still match `PID-template.md` +- output filenames still match the README and user prompts +- validation sections still require structural, evidence, privacy, quality, and receipt checks +- receipt requirements still match the current ratchet-based skill framework +- source categories still reflect the current maintenance workflow +- review-first gate is still explicit +- no private/local-only maintainer paths are required for normal user operation +- suggested prompts still mention the current skill and expected review-first behavior + +If `PID-template.md` changes, update the section mapping and validation in this skill. + ## Run Receipt -Create a receipt in the final response or in `PID-update-run-receipt-[YYYY-MM-DD].md`: +For serious use, leave a durable, inspectable receipt. Treat the receipt as the replay/audit record for the skill run, not merely a human-readable final summary. + +The receipt should let a future agent answer: + +- what skill ran +- under what version/context it ran +- what timeframe was reviewed +- what sources were authorized +- what sources were used, skipped, unavailable, or intentionally excluded +- assumptions made +- capabilities used +- tool calls or commands executed +- external state changed +- outputs produced +- validations run +- failures found +- fixes applied +- user review status +- PID update status +- ratchet artifacts added or suggested +- unresolved risks +- follow-up recommendations +- how the run could be resumed, audited, forked, or repeated + +If the receipt is compacted into a final response, preserve the full receipt as a file, JSON artifact, test log, or run directory whenever the workflow is important. A final-response summary is a projection of the receipt; it is not the receipt itself. + +Use this Markdown structure when writing `PID-update-run-receipt-[YYYY-MM-DD].md`: ```md # PID Update Run Receipt +## Skill Run + +- Skill name: +- Skill source/path: +- Skill version or file timestamp if known: +- Run date: +- Executor/host: +- User request: + ## Timeframe ## PID Source +## PID Format And Edit Method + +## Inputs Used + +- Current PID: +- Review draft: +- Revised review draft: +- User-provided instructions: +- Privacy boundaries: +- Update goals: + +## Assumptions Made + +## Capabilities Used + +- Filesystem: +- Connectors: +- Browser/network: +- Subagents: +- Document/PDF/spreadsheet tools: + +## Tool Calls Or Commands Executed + +## External State Changed + +- Files created: +- Files modified: +- Cloud documents modified: +- PID changed: +- Nothing changed without explicit user approval: + ## Approved Sources Reviewed ## Sources Skipped Or Unavailable +## Sources Not Authorized Or Intentionally Excluded + ## Draft Created ## User Review Status ## PID Update Status +## Outputs Produced + +- Review draft: +- Source map: +- Open questions: +- Updated PID or copy-ready update: +- Run receipt: + ## Validation Results ## Privacy Decisions ## Notable Inferences +## Unsupported Or Low-Confidence Items Removed, Downgraded, Or Turned Into Questions + +## Failures Or Gaps Found + +## Fixes Applied + ## Open Questions -## Skill Ratchet Suggestions +## Ratchet Lessons + +## Ratchet Artifacts Added Or Suggested + +## Unresolved Risks + +## Resume / Audit Notes + +- How a future agent can continue: +- What should be reviewed first: + +## Recommended Next Steps ``` +## Receipt Vs Final Report + +The final report is for the user. + +The run receipt is for future agents, auditors, and maintainers. + +Do not rely on the final response as the only record when files were created, source materials were interpreted, validations were run, validations were skipped, privacy decisions were made, failures were discovered, the PID was modified, or ratchet artifacts were added or suggested. + ## Final Report When finished, report concisely: @@ -555,7 +786,9 @@ When finished, report concisely: - whether the PID was updated or is awaiting review - what validations passed - what risks or open questions remain +- where the run receipt was written, or why it was not written - any suggested skill improvements learned from the run +- what ratchet artifact was added or suggested if the run exposed a recurring issue ## Suggested User Prompt