mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-08-28 04:24:58 +00:00
feat(engineering): add collab-proof skill (clean re-land of #788)
Adds the collab-proof AI-collaboration retrospective skill from PR #788 (contributor: dong7812) without the regressions in that branch: - Net-add marketplace entry (PR #788 overwrote the youtube-full plugin slot; that entry is preserved here). - marketplace.json kept as raw UTF-8 (PR #788 re-serialized with ensure_ascii, escaping ~109 chars and polluting the diff). - Header counters bumped from current dev (344 skills / 695 references / 65 plugins) instead of reverting to the stale v2.9.0 header. Skill content (SKILL.md, 4 references, plugin.json, LICENSE) is taken verbatim from #788. plugin.json passes check_plugin_json. https://claude.ai/code/session_012iCc6XcNqiJzCGfKHz1DKi
This commit is contained in:
Claude
parent
fcd4fa1b20
commit
753adb46f0
8 changed files with 682 additions and 2 deletions
|
|
@ -4,11 +4,11 @@
|
|||
"name": "Alireza Rezvani",
|
||||
"url": "https://alirezarezvani.com"
|
||||
},
|
||||
"description": "343 production-ready skill packages for Claude AI across 17 domains: engineering advanced (78, incl. v2.9.0 workflow-builder for Claude Code Workflow-tool authoring), engineering core (51), marketing (46 — incl. AEO/Answer Engine Optimization), c-level advisory (66), product (17), regulatory/QMS (18), compliance-os (9), project management (9), business growth (5), finance (4), productivity (6), marketing top-level (1), research (8), research-ops (5, v2.9.0), business-operations (7), commercial (8), and markdown-html (5, v2.10.3 — markdown-to-interactive-HTML converter complete: orchestrator + design-system + md-document long-form + md-review code-review + md-slides slide-deck). Includes 548 Python tools, 691 reference documents, 51+ agents, 90+ slash commands across 64 marketplace plugins.",
|
||||
"description": "344 production-ready skill packages for Claude AI across 17 domains: engineering advanced (78, incl. v2.9.0 workflow-builder for Claude Code Workflow-tool authoring), engineering core (51), marketing (46 — incl. AEO/Answer Engine Optimization), c-level advisory (66), product (17), regulatory/QMS (18), compliance-os (9), project management (9), business growth (5), finance (4), productivity (6), marketing top-level (1), research (8), research-ops (5, v2.9.0), business-operations (7), commercial (8), and markdown-html (5, v2.10.3 — markdown-to-interactive-HTML converter complete: orchestrator + design-system + md-document long-form + md-review code-review + md-slides slide-deck). Includes 548 Python tools, 695 reference documents, 51+ agents, 90+ slash commands across 65 marketplace plugins.",
|
||||
"homepage": "https://github.com/alirezarezvani/claude-skills",
|
||||
"repository": "https://github.com/alirezarezvani/claude-skills",
|
||||
"metadata": {
|
||||
"description": "343 production-ready skills across 17 domains (engineering, engineering-core, marketing, product, c-level, compliance-os, project management, RA/QM, business growth, finance, productivity, marketing top-level, research, research-ops, business-operations, commercial, markdown-html, plus standards). 548 Python tools, 691 reference guides, 51+ agents (cs-* + personas), 90+ slash commands across 64 marketplace plugins. v2.10.3 completes the markdown-html domain with md-slides — slide-deck converter (arrow-key / Space / PgDn / Home/End / P keyboard navigation + presenter mode with split-view clock + speaker notes + next-slide preview + URL-hash deep linking like #3 for direct slide jumps + @media print page-per-slide for browser-native PDF export). Reuses md-document's markdown parser; vanilla JS only (no framework runtime); Prism.js opt-in via --syntax. Joins md-review (v2.10.2 code-review converter), md-document (v2.10.1 long-form converter), and the v2.10.0 foundation (orchestrator + design-system). Compatible with Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Mistral Vibe, and 5 more coding agents.",
|
||||
"description": "344 production-ready skills across 17 domains (engineering, engineering-core, marketing, product, c-level, compliance-os, project management, RA/QM, business growth, finance, productivity, marketing top-level, research, research-ops, business-operations, commercial, markdown-html, plus standards). 548 Python tools, 695 reference guides, 51+ agents (cs-* + personas), 90+ slash commands across 65 marketplace plugins. v2.10.3 completes the markdown-html domain with md-slides — slide-deck converter (arrow-key / Space / PgDn / Home/End / P keyboard navigation + presenter mode with split-view clock + speaker notes + next-slide preview + URL-hash deep linking like #3 for direct slide jumps + @media print page-per-slide for browser-native PDF export). Reuses md-document's markdown parser; vanilla JS only (no framework runtime); Prism.js opt-in via --syntax. Joins md-review (v2.10.2 code-review converter), md-document (v2.10.1 long-form converter), and the v2.10.0 foundation (orchestrator + design-system). Compatible with Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes Agent, Mistral Vibe, and 5 more coding agents.",
|
||||
"version": "2.10.3"
|
||||
},
|
||||
"plugins": [
|
||||
|
|
@ -1448,6 +1448,24 @@
|
|||
"transcriptapi"
|
||||
],
|
||||
"category": "marketing"
|
||||
},
|
||||
{
|
||||
"name": "collab-proof",
|
||||
"source": "./engineering/collab-proof",
|
||||
"description": "Assisted retrospective: after a session, calibrates what Claude contributed vs what the developer drove. LLM-assessed 4-frame analysis with explicit rubric, zero dependencies.",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "dong7812",
|
||||
"url": "https://github.com/dong7812"
|
||||
},
|
||||
"keywords": [
|
||||
"ai-collaboration",
|
||||
"session-retrospective",
|
||||
"git-analysis",
|
||||
"decision-logging",
|
||||
"collab-proof"
|
||||
],
|
||||
"category": "engineering"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
15
engineering/collab-proof/.claude-plugin/plugin.json
Normal file
15
engineering/collab-proof/.claude-plugin/plugin.json
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
{
|
||||
"name": "collab-proof",
|
||||
"description": "Assisted retrospective: after a session, calibrates what Claude contributed vs what the developer drove. LLM-assessed 4-frame analysis, zero dependencies.",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "dong7812",
|
||||
"url": "https://github.com/dong7812"
|
||||
},
|
||||
"homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/collab-proof",
|
||||
"repository": "https://github.com/alirezarezvani/claude-skills",
|
||||
"license": "MIT",
|
||||
"skills": [
|
||||
"./skills/collab-proof"
|
||||
]
|
||||
}
|
||||
21
engineering/collab-proof/LICENSE
Normal file
21
engineering/collab-proof/LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 dong7812
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
383
engineering/collab-proof/skills/collab-proof/SKILL.md
Normal file
383
engineering/collab-proof/skills/collab-proof/SKILL.md
Normal file
|
|
@ -0,0 +1,383 @@
|
|||
---
|
||||
name: "collab-proof"
|
||||
description: "Use when you want to understand what Claude contributed vs what you drove in a session. Triggers on: /collab-proof, session retrospective, ai contribution analysis, collaboration evidence, what did claude do."
|
||||
license: MIT
|
||||
---
|
||||
|
||||
# collab-proof
|
||||
|
||||
Surfaces AI collaboration evidence the developer didn't consciously record.
|
||||
Vela 3-layer pipeline × ADHD 4-frame reasoning — prompt-native, zero dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Layer 01 — Signal detection
|
||||
|
||||
Run `git log --oneline -10` and `git diff --stat HEAD~3..HEAD` first.
|
||||
|
||||
Classify signal level using this rubric (pick the highest that matches):
|
||||
|
||||
**HIGH** → full artifacts (DECISIONS.md + session-history + WORKLOG + HTML)
|
||||
- New file created, OR
|
||||
- 4+ files modified, OR
|
||||
- Explicit option comparison in conversation ("vs", "instead of", "chose X over Y"), OR
|
||||
- Design discussion lasted 15+ exchanges, OR
|
||||
- **Bug with root cause diagnosis** — conversation contains WHY the bug happened
|
||||
(not just "fixed X" but "the bug was caused by Y because Z")
|
||||
|
||||
**BUG_FIXING special rule** — override file count:
|
||||
Even if only 1 file changed, classify as HIGH if the conversation contains:
|
||||
- Root cause explanation ("the bug was...", "this happened because...", "the issue is...")
|
||||
- Diagnosis process ("I checked...", "turned out...", "the problem was...")
|
||||
- Fix rationale ("chose this approach because...", "instead of X, used Y because...")
|
||||
File count doesn't matter for bugs — a well-diagnosed single-file fix is more valuable
|
||||
than a 10-file feature with no discussion.
|
||||
|
||||
**MEDIUM** → WORKLOG only
|
||||
- 1–3 files modified with no root cause discussion, OR
|
||||
- Minor feature added, no tradeoffs discussed
|
||||
|
||||
**LOW** → silence, tell user "Routine session — nothing recorded."
|
||||
- No code changes, only planning/discussion, OR
|
||||
- Single trivial change with no context ("change this text", "fix typo", "rename variable")
|
||||
|
||||
Show the user: `Signal: HIGH / MEDIUM / LOW — [one-line reason]`
|
||||
|
||||
---
|
||||
|
||||
## Layer 02 — WorkIntentClassifier
|
||||
|
||||
Run all four frames simultaneously against conversation context + git diff.
|
||||
Score each frame 0.0–1.0 using the rubric below. Then apply pruning and classification rules.
|
||||
|
||||
### Frame scoring rubric
|
||||
|
||||
**Frame A — Technical** (code churn complexity)
|
||||
- `1.0` New module/file created, complex logic added (state machine, Lua script, novel algorithm)
|
||||
- `0.5` Existing function logic modified, simple API endpoint added
|
||||
- `0.1` Typo fix, comment change, plain text edit
|
||||
|
||||
**Frame B — Uncertainty** (developer doubt signals)
|
||||
- `1.0` Code written then fully rolled back, explicit doubt expressed ("이게 맞나?", "동작 안 하네"), `git revert`
|
||||
- `0.5` Advice sought from Claude mid-implementation, 2+ revision requests on same area
|
||||
- `0.0` Uninterrupted directive execution — developer knew exactly what to build
|
||||
|
||||
**Frame C — Fork** (decision branch presence)
|
||||
- `1.0` Two or more alternatives explicitly compared in conversation (A vs B)
|
||||
- `0.5` No explicit comparison but tradeoff mentioned (performance vs readability)
|
||||
- `0.0` Single standard approach applied, no alternatives considered
|
||||
|
||||
**Frame D — AI contribution** (Claude's actual impact)
|
||||
- `1.0` Claude identified a bug/edge case the developer hadn't noticed and proposed the fix
|
||||
- `0.6` Claude generated structural boilerplate/skeleton that significantly accelerated execution
|
||||
- `0.2` Claude reformatted or transcribed developer-directed code without independent contribution
|
||||
|
||||
---
|
||||
|
||||
### Pruning rule
|
||||
|
||||
Prune any frame scoring < 0.4.
|
||||
|
||||
**Exception — High-Speed Execution Guard:**
|
||||
If `Frame A >= 0.8` AND `Frame D >= 0.6`, do NOT prune and do NOT silence the session,
|
||||
even if Frame B = 0.0 and Frame C = 0.0.
|
||||
This is a boilerplate-heavy FEATURE_BUILDING session. Classify immediately as `FEATURE_BUILDING` with `HIGH` signal.
|
||||
Rationale: zero uncertainty in a fast-moving session is a feature, not a reason to discard it.
|
||||
|
||||
---
|
||||
|
||||
### Intent classification
|
||||
|
||||
| Surviving frames | Dominant intent | Meaning |
|
||||
|---|---|---|
|
||||
| A high + D mid-high (B, C low) | `FEATURE_BUILDING` | High-velocity feature generation, Claude scaffolding |
|
||||
| B high + A/D high | `BUG_FIXING` or `STUCK` | Active debugging or unresolved looping |
|
||||
| C high + A high | `REFACTORING` or `EXPLORING` | Architecture exploration, weighing alternatives |
|
||||
| All frames < 0.4 | `FLOW_STATE` or LOW | Routine typing, silence unless Layer 01 was HIGH |
|
||||
|
||||
If multiple intents tie, pick the one with the highest combined frame score.
|
||||
Record the runner-up — it belongs in the session narrative.
|
||||
|
||||
---
|
||||
|
||||
### Internal output format
|
||||
|
||||
Before proceeding to Layer 03, resolve to this structure (show it to the user):
|
||||
|
||||
```json
|
||||
{
|
||||
"frames": {
|
||||
"technical": 0.0,
|
||||
"uncertainty": 0.0,
|
||||
"fork": 0.0,
|
||||
"ai_contribution": 0.0
|
||||
},
|
||||
"pruned": ["list of pruned frame names"],
|
||||
"intent": "FEATURE_BUILDING",
|
||||
"signal": "HIGH",
|
||||
"calibration_note": "one sentence explaining any exception rule applied"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layer 03 — Output
|
||||
|
||||
### If HIGH signal
|
||||
|
||||
**Append to `DECISIONS.md`** — one entry per real fork (Frame C must confirm alternatives existed):
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD] <title>
|
||||
|
||||
**Context**: [Frame A — what forced this choice]
|
||||
**Decision**: what was chosen
|
||||
**Alternatives considered**: [Frame C — road not taken]
|
||||
**Reasoning**: why — prefix "inferred:" if reconstructed from context
|
||||
**AI contribution**:
|
||||
- Identified: [Frame D — something developer missed]
|
||||
- Suggested: [Frame D — approach or alternative]
|
||||
- Developer-driven: [what the developer decided independently]
|
||||
**Intent class**: [from Layer 02]
|
||||
**Signal score**: HIGH
|
||||
**Outcome**: implemented | pending | reversed
|
||||
```
|
||||
|
||||
If no real fork existed → write nothing. Never fabricate decisions.
|
||||
|
||||
**BUG_FIXING intent: use this format instead:**
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD] <bug title>
|
||||
|
||||
**Root cause**: what actually caused the bug — the WHY, not just the what
|
||||
**Symptom**: what the developer observed
|
||||
**Fix**: what was changed
|
||||
**Why this fix**: rationale — inferred if not stated explicitly
|
||||
**Alternative fixes considered**: other approaches discussed (if any)
|
||||
**AI contribution**:
|
||||
- Identified: [Frame D — did Claude spot the root cause?]
|
||||
- Suggested: [Frame D — fix approach or diagnostic step]
|
||||
- Developer-driven: [what the developer diagnosed/decided independently]
|
||||
**Intent class**: BUG_FIXING
|
||||
**Signal score**: HIGH
|
||||
**Outcome**: fixed | workaround | deferred
|
||||
```
|
||||
|
||||
**Create `session-history/YYYY-MM-DD-HHMM.md`**:
|
||||
|
||||
```markdown
|
||||
# Session [YYYY-MM-DD HH:MM]
|
||||
|
||||
**Intent**: [class] (runner-up: [class if any])
|
||||
**Signal**: HIGH
|
||||
**Frames active**: A ([score]) / B ([score]) / C ([score]) / D ([score])
|
||||
|
||||
## What shipped
|
||||
[grounded in git log]
|
||||
|
||||
## What was figured out
|
||||
[Frame B + C — the reasoning, tradeoffs, debugging — what developers forget]
|
||||
|
||||
## Decisions made this session
|
||||
[refs to DECISIONS.md entries]
|
||||
|
||||
## Where it got hard
|
||||
[Frame B findings — uncertainty, reverts, EXPLORING/STUCK signals]
|
||||
|
||||
## AI contribution summary
|
||||
[Frame D synthesis — one honest paragraph, calibrated]
|
||||
|
||||
## Next steps inferred
|
||||
[what's obviously incomplete]
|
||||
```
|
||||
|
||||
**Append to `WORKLOG.md`**:
|
||||
```
|
||||
YYYY-MM-DD HH:MM | [intent] | HIGH | D:[score] | cache:[hit%]% | tok:[total] | <verb phrase> — <why it mattered>
|
||||
```
|
||||
|
||||
Fields:
|
||||
- `D:[score]` — Frame D AI contribution score (0.0–1.0)
|
||||
- `cache:[hit%]%` — cache hit rate from token analysis (or `cache:n/a` if no data)
|
||||
- `tok:[total]` — total tokens this session (input + cache_read + cache_create + output, in K e.g. `45K`)
|
||||
- verb phrase — what shipped, grounded in git log
|
||||
|
||||
**Collect token usage** (bash — run this and capture output):
|
||||
```bash
|
||||
python3 -c "
|
||||
import json, sys
|
||||
from pathlib import Path
|
||||
|
||||
projects = Path.home() / '.claude/projects'
|
||||
files = sorted(projects.rglob('*.jsonl'), key=lambda f: f.stat().st_mtime, reverse=True)
|
||||
if not files:
|
||||
print('no_data'); sys.exit()
|
||||
|
||||
with open(files[0]) as fp:
|
||||
lines = [json.loads(l) for l in fp if l.strip()]
|
||||
|
||||
ti = to = cr = cc = 0
|
||||
turns = []
|
||||
for i, line in enumerate(lines):
|
||||
if line.get('type') == 'assistant':
|
||||
u = line.get('message', {}).get('usage', {})
|
||||
if not u: continue
|
||||
inp = u.get('input_tokens', 0)
|
||||
ti += inp; to += u.get('output_tokens', 0)
|
||||
cr += u.get('cache_read_input_tokens', 0)
|
||||
cc += u.get('cache_creation_input_tokens', 0)
|
||||
prompt = ''
|
||||
for j in range(i-1, -1, -1):
|
||||
if lines[j].get('type') == 'user':
|
||||
c = lines[j].get('message', {}).get('content', '')
|
||||
prompt = (c if isinstance(c, str) else next((x.get('text','') for x in c if isinstance(x,dict) and x.get('type')=='text'), ''))[:80]
|
||||
break
|
||||
turns.append((inp, prompt))
|
||||
|
||||
total = ti + cr + cc
|
||||
hit = cr / total * 100 if total else 0
|
||||
print(f'input={ti} output={to} cache_read={cr} cache_create={cc} hit={hit:.0f} turns={len(turns)}')
|
||||
turns.sort(reverse=True)
|
||||
for idx, (tok, p) in enumerate(turns[:3]):
|
||||
print(f'top{idx+1}={tok}|{p}')
|
||||
"
|
||||
```
|
||||
|
||||
Parse the output and include token stats in the session narrative. Then:
|
||||
|
||||
**Generate `session-history/YYYY-MM-DD-HHMM-proof.html`** — write a self-contained HTML file. Structure and class names are fixed — do not rename or reorder sections.
|
||||
|
||||
**Fixed CSS tokens (use exactly):**
|
||||
- Background: `#0d1117`, Card: `#161b22`, Border: `#30363d`
|
||||
- Font: `font-family: 'Courier New', monospace`
|
||||
- Frame score colors: `high` → `#3fb950`, `low` → `#f85149`, pruned → `#8b949e`
|
||||
- AI line colors: `ai-identified` → `#a371f7`, `ai-suggested` → `#d29922`, `ai-developer` → `#3fb950`
|
||||
|
||||
**Fixed HTML structure (class names must match exactly):**
|
||||
```
|
||||
<div class="header">
|
||||
<div class="header-top">
|
||||
<div class="project-name">
|
||||
<span class="badge"> <!-- intent class -->
|
||||
<div class="meta-row"> <!-- date, branch, signal level text -->
|
||||
<div class="signal-container">
|
||||
<div class="signal-label">
|
||||
<div class="signal-track">
|
||||
<div class="signal-fill"> <!-- width % driven by signal score -->
|
||||
|
||||
<div class="section"> <!-- frames -->
|
||||
<div class="section-title"> ... <span class="count">Layer 02 · ADHD tree-of-thought</span>
|
||||
<div class="frames-grid">
|
||||
<div class="frame-card"> <!-- pruned: class="frame-card pruned" -->
|
||||
<div class="frame-label"> <!-- Frame A / B / C / D -->
|
||||
<div class="frame-name">
|
||||
<div class="frame-score high|low"> <!-- score value -->
|
||||
|
||||
<div class="section"> <!-- decisions — skip section if none -->
|
||||
<div class="section-title"> ... <span class="count">N recorded</span>
|
||||
<div class="decision-card"> <!-- one per DECISIONS.md entry -->
|
||||
<div class="decision-header">
|
||||
<div class="decision-title">
|
||||
<div class="decision-date">
|
||||
<div class="decision-fields">
|
||||
<div class="field-row">
|
||||
<div class="field-label"> <!-- Context / Decision / Alternatives / Reasoning -->
|
||||
<div class="field-value">
|
||||
<div class="field-row"> <!-- AI contribution row -->
|
||||
<div class="field-label">AI contribution</div>
|
||||
<div class="field-value">
|
||||
<div class="ai-block">
|
||||
<div class="ai-line ai-identified|ai-suggested|ai-developer">
|
||||
<span class="tag">IDENTIFIED|SUGGESTED|DEV-DRIVEN</span>
|
||||
<div class="field-row"> <!-- Outcome row -->
|
||||
<div class="field-label">Outcome</div>
|
||||
<div class="field-value">
|
||||
<span class="outcome-badge outcome-implemented|outcome-pending|outcome-reversed">
|
||||
|
||||
<div class="section"> <!-- session narrative -->
|
||||
<div class="section-title">Session narrative</div>
|
||||
<div class="narrative-grid">
|
||||
<div class="narrative-card"> <!-- What shipped -->
|
||||
<div class="narrative-card"> <!-- What was figured out -->
|
||||
<div class="narrative-card"> <!-- Where it got hard -->
|
||||
<div class="narrative-card"> <!-- Next steps inferred -->
|
||||
|
||||
<div class="section"> <!-- AI contribution summary -->
|
||||
<div class="section-title">AI contribution summary</div>
|
||||
<div class="narrative-card"> <!-- Frame D synthesis paragraph -->
|
||||
|
||||
<div class="section"> <!-- token usage -->
|
||||
<div class="section-title">Token usage</div>
|
||||
<div class="narrative-card"> <!-- cache hit rate bar + top turns + optimization note -->
|
||||
|
||||
<div class="section"> <!-- worklog tail -->
|
||||
<div class="section-title"> ... <span class="count">last N entries</span>
|
||||
<div class="worklog-entry"> <!-- one per recent WORKLOG line -->
|
||||
|
||||
<div class="footer"> <!-- last commit hash · "Generated by collab-proof · timestamp" -->
|
||||
```
|
||||
|
||||
Write the HTML using bash:
|
||||
```bash
|
||||
cat > session-history/YYYY-MM-DD-HHMM-proof.html << 'HTMLEOF'
|
||||
<!DOCTYPE html>
|
||||
... (full HTML with inline CSS, no external resources)
|
||||
HTMLEOF
|
||||
```
|
||||
|
||||
After writing, show: `open session-history/YYYY-MM-DD-HHMM-proof.html`
|
||||
|
||||
---
|
||||
|
||||
### If MEDIUM signal
|
||||
|
||||
Append one line to `WORKLOG.md` only:
|
||||
```
|
||||
YYYY-MM-DD HH:MM | [intent] | MEDIUM | D:[score] | cache:[hit%]% | tok:[total] | <verb phrase>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### If LOW signal
|
||||
|
||||
Tell user: "Signal: LOW — Routine session, nothing recorded."
|
||||
|
||||
---
|
||||
|
||||
## Honesty rules
|
||||
|
||||
- Never invent decisions not in the conversation or implied by the diff
|
||||
- "inferred:" prefix when reasoning is reconstructed
|
||||
- Frame D must be calibrated — neither overclaim nor dismiss
|
||||
- If all frames score < 0.4 → write nothing
|
||||
|
||||
---
|
||||
|
||||
## PreCompact snapshot (context compaction defence)
|
||||
|
||||
When context compaction is about to happen (triggered by the PreCompact hook),
|
||||
run a lightweight mid-session checkpoint before context is lost:
|
||||
|
||||
1. Compute current Layer 01 signal level from available context
|
||||
2. Score all four frames against what's visible now
|
||||
3. Write a snapshot to `session-history/.tmp-TIMESTAMP.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "YYYY-MM-DD HH:MM:SS",
|
||||
"trigger": "pre-compact",
|
||||
"signal": "HIGH / MEDIUM / LOW",
|
||||
"frames": { "technical": 0.0, "uncertainty": 0.0, "fork": 0.0, "ai_contribution": 0.0 },
|
||||
"intent": "FEATURE_BUILDING",
|
||||
"key_moments": [
|
||||
"one-line description of the most important decision or finding so far"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When `/collab-proof` runs at session end:
|
||||
- Read all `session-history/.tmp-*.json` files
|
||||
- Merge frame scores (take max per frame across all snapshots)
|
||||
- Combine `key_moments` arrays — these preserve tradeoff discussions that were compacted away
|
||||
- Delete `.tmp-*.json` files after merging
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
# AI Collaboration Evidence: Why Documentation Matters
|
||||
|
||||
## The Problem
|
||||
|
||||
Developers increasingly build with AI, but the collaboration leaves no trace. Git log records *what* changed; the conversation records *what was said*. Neither answers the questions that matter most:
|
||||
|
||||
- Why was this approach chosen over the alternative?
|
||||
- What did the AI identify that the developer hadn't noticed?
|
||||
- Where did the developer override the AI's suggestion — and why?
|
||||
|
||||
## Key Sources
|
||||
|
||||
**1. Hiring and Portfolio Verification (2025–2026)**
|
||||
Companies now explicitly ask candidates to show AI collaboration evidence. GitHub portfolios require "a 'My contribution' section linking to commits or pull requests that demonstrate what you owned" (Artech, 2026). Recruiters scan for AI-native engineering skills and expect proof beyond finished artifacts.
|
||||
Source: [Artech AI Portfolio Tips](https://www.artech.com/blog/ai-assisted-portfolio-credibility/)
|
||||
|
||||
**2. Architecture Decision Records (ADRs)**
|
||||
ADRs (Michael Nygard, 2011) capture the context, decision, and consequences of architectural choices. The canonical format includes: title, status, context, decision, consequences. Modern AI-assisted development extends this pattern to include *who* made the decision — human or AI.
|
||||
Source: [Nygard ADR Template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
|
||||
|
||||
**3. Session Context Loss**
|
||||
Claude Code saves session transcripts to `~/.claude/projects/` as JSONL. But context compaction and session boundaries mean reasoning evaporates. Studies of AI-assisted development show developers cannot reconstruct the reasoning behind 60–70% of decisions made in a session after 48 hours.
|
||||
Source: [Claude Code Session Memory](https://claudefa.st/blog/guide/mechanics/session-memory)
|
||||
|
||||
**4. AI Contribution Attribution**
|
||||
The `git-ai` project (2026) tracks AI-generated code line-by-line. But line attribution ("AI wrote this") is different from decision attribution ("AI identified this issue"). collab-proof targets the decision layer, not the code layer.
|
||||
Source: [git-ai: AI contribution tracking](https://github.com/git-ai-project/git-ai)
|
||||
|
||||
**5. Developer Cognitive Load**
|
||||
Research on expertise and memory (Sweller, 1988; Kirschner et al., 2006) shows that working memory constraints cause implicit reasoning to be discarded when focus shifts. External documentation of decisions during the session — not after — is the only reliable capture method.
|
||||
Source: Sweller, J. (1988). Cognitive load during problem solving. *Cognitive Science*, 12(2), 257–285.
|
||||
|
||||
## Implications for collab-proof
|
||||
|
||||
- Evidence must be captured *during* the session, not reconstructed afterward
|
||||
- Calibrated attribution ("identified" vs "suggested" vs "developer-driven") is more useful than binary AI/human labeling
|
||||
- Shareable HTML format enables portfolio and hiring use cases that markdown alone cannot serve
|
||||
- Signal filtering prevents noise — only sessions with genuine decision forks produce output
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
# Developer Portfolio Proof: The AI Collaboration Evidence Problem
|
||||
|
||||
## Why "Show Your Work" Now Applies to AI
|
||||
|
||||
The hiring market has shifted. Companies explicitly ask candidates: "Show me how you used AI in this project." The challenge is that AI-assisted development leaves ambiguous evidence:
|
||||
|
||||
- A GitHub repo shows finished code, not the collaboration process
|
||||
- Commit messages show *what* shipped, not *why* this approach
|
||||
- A demo shows the product works, not what the developer contributed vs the AI
|
||||
|
||||
## The Verification Gap
|
||||
|
||||
Source: [TechnCV: Claude Code Resume Skills](https://techncv.com/blog/claude-code-resume-skills/)
|
||||
|
||||
Hiring managers at forward-thinking companies scan for AI-native engineering skills. The recommended evidence includes:
|
||||
1. Git commit histories with meaningful messages
|
||||
2. Prompt logs or decision rationale
|
||||
3. Inline comments explaining decisions
|
||||
4. Live demos where candidates walk through their logic
|
||||
|
||||
collab-proof addresses items 2 and 3 automatically.
|
||||
|
||||
## HTML as Portable Proof
|
||||
|
||||
Markdown files are local artifacts. HTML files are shareable:
|
||||
- Email attachment to a recruiter
|
||||
- Link in a GitHub README
|
||||
- Appendix to a portfolio site
|
||||
- PR description for code review
|
||||
|
||||
A self-contained HTML file (no CDN, no external resources, `file://`-ready) is the most portable format for portfolio evidence. PDF requires generation tooling; Gist requires GitHub authentication.
|
||||
|
||||
Source: [AI Agent Portfolio Examples](https://tandamconnect.com/blog/ai-agent-portfolio-examples-2026)
|
||||
|
||||
## The "AI Contribution" Calibration Problem
|
||||
|
||||
Existing tools either overclaim ("AI built this") or dismiss ("developer did everything"). Neither is useful for:
|
||||
- Honest self-assessment
|
||||
- Team knowledge transfer
|
||||
- Portfolio credibility
|
||||
|
||||
The calibrated approach distinguishes three contribution types:
|
||||
- **Identified**: AI spotted something the developer hadn't noticed (e.g., race condition, security issue)
|
||||
- **Suggested**: AI proposed an approach or alternative (developer made final call)
|
||||
- **Developer-driven**: Developer designed and decided; AI executed
|
||||
|
||||
This three-way split comes from studies of pair programming (Williams & Kessler, 2002) where contribution attribution improved team learning and code review quality.
|
||||
|
||||
Source: Williams, L. & Kessler, R. (2002). *Pair Programming Illuminated*. Addison-Wesley.
|
||||
|
||||
## Signal Filtering Prevents Portfolio Inflation
|
||||
|
||||
Not every session deserves documentation. A session where you changed a button color has no evidence value. collab-proof's LOW signal threshold silences these sessions.
|
||||
|
||||
The 30–40% artifact generation rate is a feature, not a bug: it means every documented session has genuine decision content, making the portfolio more credible, not less.
|
||||
|
||||
Source: [Asking HN: Hiring in the age of AI-assisted coding](https://news.ycombinator.com/item?id=47722081)
|
||||
|
||||
## Tamper-Evident Timestamps via Git
|
||||
|
||||
The HTML proof footer embeds the last git commit hash of the session. This provides:
|
||||
- A timestamp verifiable against the public git history
|
||||
- Proof the document was generated at development time, not retrospectively
|
||||
- A link between the artifact and the code it describes
|
||||
|
||||
This is analogous to signed commits but for documentation rather than code.
|
||||
|
||||
Source: [Git: Cryptographic signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
# Session Documentation Patterns
|
||||
|
||||
## Existing Approaches and Their Gaps
|
||||
|
||||
### Architecture Decision Records (ADRs)
|
||||
ADRs (Nygard, 2011) are the standard for capturing architectural decisions. Format: context → decision → consequences. Tools like `madr-gen` auto-generate ADRs from Claude Code sessions using MADR 4.0 format.
|
||||
|
||||
**Gap**: ADRs don't capture *who* made the decision. In AI-assisted development, "decision" can mean "Claude suggested and developer accepted," "developer decided over Claude's objection," or "collaborative synthesis." Without this distinction, ADRs are incomplete evidence.
|
||||
|
||||
Source: [MADR format](https://adr.github.io/madr/), [madr-gen](https://github.com/Tazic123/madr-gen)
|
||||
|
||||
### Session Loggers (claude-sessions, claude-diary)
|
||||
Tools like `maleta/claude-sessions` automatically summarize Claude Code sessions and generate `SESSION_SUMMARIES.md`. `rlancemartin/claude-diary` creates diary entries from session transcripts.
|
||||
|
||||
**Gap**: These tools answer "what happened?" not "what was the reasoning?" and not "what did each party contribute?" They're logs, not decision records.
|
||||
|
||||
Source: [maleta/claude-sessions](https://github.com/maleta/claude-sessions), [claude-diary](https://github.com/rlancemartin/claude-diary)
|
||||
|
||||
### Memory Compilers (claude-memory-compiler)
|
||||
`coleam00/claude-memory-compiler` uses hooks to capture sessions, extracts key decisions with the Claude Agent SDK, and compiles cross-referenced knowledge articles.
|
||||
|
||||
**Gap**: Heavy setup (requires Agent SDK), no HTML export, no calibrated attribution field.
|
||||
|
||||
Source: [claude-memory-compiler](https://github.com/coleam00/claude-memory-compiler)
|
||||
|
||||
## The Signal Filtering Pattern
|
||||
|
||||
Not all sessions deserve documentation. Vela's 3-layer pipeline (signal detection → intent classification → output generation) filters noise before generating artifacts:
|
||||
|
||||
- **Layer 01 (Signal)**: git diff + conversation analysis → HIGH/MEDIUM/LOW
|
||||
- **Layer 02 (Intent)**: ADHD 4-frame parallel reasoning → intent class
|
||||
- **Layer 03 (Output)**: proportional artifact generation
|
||||
|
||||
This prevents the "everything is documented" anti-pattern where signal-to-noise ratio collapses.
|
||||
|
||||
Reference: Signal-filtering pipeline pattern — see [collab-proof SKILL.md](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/collab-proof/skills/collab-proof/SKILL.md)
|
||||
|
||||
## ADHD Tree-of-Thought in Layer 02
|
||||
|
||||
The ADHD tree-of-thought approach (UditAkhourii, 2025) fans out parallel divergent thoughts under different cognitive frames, scores, prunes traps, and deepens survivors.
|
||||
|
||||
Applied to session analysis, four frames fire simultaneously:
|
||||
- **Frame A (Technical)**: What code choices were made?
|
||||
- **Frame B (Uncertainty)**: Where was the developer unsure?
|
||||
- **Frame C (Fork)**: What could have gone differently?
|
||||
- **Frame D (AI contribution)**: Where did Claude change the outcome?
|
||||
|
||||
Frames scoring below 0.4 are pruned. Only surviving frames contribute to output.
|
||||
|
||||
Source: [UditAkhourii/adhd](https://github.com/uditakhourii/adhd), [The New Stack: Claude Code ADHD](https://thenewstack.io/claude-code-adhd/)
|
||||
|
||||
## SessionEnd Hook (Claude Code 1.0.84+)
|
||||
|
||||
Claude Code introduced the `SessionEnd` hook in version 1.0.84. It fires when the session closes, enabling full automation without user action.
|
||||
|
||||
```json
|
||||
"hooks": {
|
||||
"SessionEnd": [{
|
||||
"hooks": [{"type": "command", "command": "~/.claude/hooks/collab-proof-on-session-end.sh"}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
Known issue: `SessionEnd` hook may report "Hook cancelled" even on exit 0 (GitHub issue #63495, open as of 2026-06). Hook executes correctly despite the warning.
|
||||
|
||||
Source: [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks), [Issue #63495](https://github.com/anthropics/claude-code/issues/63495)
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
# Tamper-Evident Proof via Git Notes
|
||||
|
||||
## The Problem with Markdown-Only Evidence
|
||||
|
||||
A DECISIONS.md file in a git repo can be backdated, edited, or fabricated. Without an immutable timestamp tied to the actual code state, it's not proof — it's documentation.
|
||||
|
||||
## Git Notes: Metadata Without File Tree Pollution
|
||||
|
||||
Git notes (`git notes`) attach arbitrary text to any git object (commit, blob, tree) without modifying the object itself. Notes live in `refs/notes/collab-proof` — a parallel namespace that doesn't appear in `git log` by default and doesn't affect `git status`.
|
||||
|
||||
```bash
|
||||
# Attach a note to the current commit
|
||||
git notes add -m "collab-proof sha256: abc123..." HEAD
|
||||
|
||||
# View notes on a commit
|
||||
git notes show HEAD
|
||||
git log --show-notes
|
||||
|
||||
# Share notes with collaborators
|
||||
git push origin refs/notes/collab-proof
|
||||
|
||||
# Fetch collaborators' notes
|
||||
git fetch origin refs/notes/collab-proof:refs/notes/collab-proof
|
||||
```
|
||||
|
||||
Source: [Git Notes documentation](https://git-scm.com/docs/git-notes), [Pro Git: Git Notes](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec)
|
||||
|
||||
## Why SHA-256 of the HTML File
|
||||
|
||||
The HTML proof file contains the full session narrative, decision records, and AI contribution analysis. Hashing it and attaching the hash to a specific commit creates a verifiable chain:
|
||||
|
||||
```
|
||||
commit abc1234 (code state at session end)
|
||||
└── git note: collab-proof sha256: f7a3...
|
||||
file: 2026-06-01-1422-proof.html
|
||||
|
||||
→ Anyone with the HTML file can verify:
|
||||
python3 -c "import hashlib; print(hashlib.sha256(open('proof.html','rb').read()).hexdigest())"
|
||||
# must match the hash in the git note
|
||||
```
|
||||
|
||||
This is structurally similar to software release signing (GPG-signed tags) but using stdlib Python and git's built-in notes system.
|
||||
|
||||
Source: [Git tag signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work), NIST SP 800-107 Rev 1 (SHA-256 collision resistance)
|
||||
|
||||
## Collaboration Safety
|
||||
|
||||
Git notes don't cause merge conflicts the way file edits do. Multiple contributors can append notes to the same commit independently:
|
||||
|
||||
```bash
|
||||
# Both developers can run this without conflict:
|
||||
git notes append -m "reviewer: approved" HEAD
|
||||
```
|
||||
|
||||
The `append` subcommand concatenates to existing notes; `add` replaces them. collab-proof uses `append` so multiple session runs on the same commit accumulate rather than overwrite.
|
||||
|
||||
Source: [git-notes man page](https://git-scm.com/docs/git-notes#_commands)
|
||||
|
||||
## Limitations
|
||||
|
||||
- Notes are not included in a standard `git clone` — collaborators must explicitly `git fetch origin refs/notes/collab-proof`
|
||||
- Notes can still be deleted with `git notes remove` — they are tamper-evident, not tamper-proof
|
||||
- The proof is only as strong as the git history itself (rebasing changes commit hashes)
|
||||
|
||||
Source: [Stack Overflow: Are git notes included in clone?](https://stackoverflow.com/questions/13935467/are-git-notes-included-in-a-git-clone)
|
||||
|
||||
## Why Not GPG Signing?
|
||||
|
||||
GPG signing would require key management infrastructure. git notes + SHA-256 achieves the core goal (linking an artifact to a specific code state at a specific time) with zero additional tooling. The threat model for developer portfolio evidence doesn't require cryptographic non-repudiation — it requires enough friction that casual fabrication is detectable.
|
||||
|
||||
Source: Schneier, B. (2003). *Beyond Fear*. Copernicus Books. (threat modeling: cost of attack vs. cost of defense)
|
||||
Loading…
Add table
Reference in a new issue