ai-brag-document

Files (1)

• SKILL.md

SKILL.md (first lines)

# AI Brag Document

Create a concise, evidence-based record of engineering impact that is useful for performance reviews, promotion discussions, calibration, and career reflection.

The document must answer five questions quickly:

1. What changed?
2. Why did it matter?
3. What did the author personally own?
4. What evidence supports the claim?
5. Is the result confirmed, expected, targeted, or still in progress?

## Workflow

Follow these steps in order:

1. Determine the scope and reporting period.
2. Discover relevant work and supporting evidence.
3. Build an internal evidence ledger.
4. Group related work into impact narratives.
5. Write the executive summary.
6. Write the main impact sections.
7. Separate work in progress and unverified outcomes.
8. Add a technical evidence appendix.
9. Run the quality checks.
10. Write the result to `$OBSIDIAN_AI_VAULT/brag-document.md` (default `$HOME/Documents/obsidian/obsidian/brag-document.md`) and verify the persisted file.
11. Ensure `$OBSIDIAN_AI_VAULT/engineering/index.md` links to the brag document.
12. Stage only the generated files and delegate the commit to the `ai-commit` skill (it targets the vault repo, never the code repo).

## Obsidian vault I/O

The Obsidian vault is the mandatory source of truth for the brag document. Read the source notes directly from the filesystem and write the generated document directly back to the same vault.

The vault root resolves from `$OBSIDIAN_AI_VAULT` (defaults to `$HOME/Documents/obsidian/obsidian` if unset) — the same override point used by every `ai-*` skill. Always use these resolved paths:

```bash
VAULT_PATH="${OBSIDIAN_AI_VAULT:-$HOME/Documents/obsidian/obsidian}"
ENGINEERING_PATH="$VAULT_PATH/engineering"
ENGINEERING_INDEX="$ENGINEERING_PATH/index.md"
BRAG_DOCUMENT="$VAULT_PATH/brag-document.md"
```

### Verify the vault

```bash
VAULT_PATH="${OBSIDIAN_AI_VAULT:-$HOME/Documents/obsidian/obsidian}"
ENGINEERING_PATH="$VAULT_PATH/engineering"
ENGINEERING_INDEX="$ENGINEERING_PATH/index.md"
BRAG_DOCUMENT="$VAULT_PATH/brag-document.md"

test -d "$VAULT_PATH" || {
  echo "Obsidian vault not found: $VAULT_PATH" >&2
  exit 1
}

test -d "$ENGINEERING_PATH" || {
  echo "Engineering vault tree not found: $ENGINEERING_PATH" >&2
  exit 1
}
```

Stop when the fixed vault or its `engineering/` tree does not exist. The vault must also be a Git repository:

```bash
git -C "$VAULT_PATH" rev-parse --is-inside-work-tree >/dev/null || {
  echo "Obsidian vault is not a Git repository: $VAULT_PATH" >&2
  exit 1
}
```

Before changing files, inspect the repository state. Unrelated unstaged changes may remain, but the staging area must be empty so the brag-document commit cannot absorb another task:

```bash
git -C "$VAULT_PATH" status --short

if ! git -C "$VAULT_PATH" diff --cached --quiet; then
  echo "The Obsidian vault already has staged changes. Commit or unstage them before running this skill." >&2
  git -C "$VAULT_PATH" diff --cached --name-only >&2
  exit 1
fi
```

### Discover source notes

Collect candidate evidence from the **entire Engineering tree** at `$OBSIDIAN_AI_VAULT/engineering` (default `$HOME/Documents/obsidian/obsidian/engineering`). This is mandatory. Do not limit discovery to repositories already mentioned by the user, the current brag document, recently edited notes, or the first matching workplan.

Search the whole Engineering tree in multiple passes. Complete every pass before deciding which accomplishments belong in the brag document.

#### Pass 1 — Inventory every Engineering note

Create a complete, sorted inventory of Markdown notes and inspect the directory structure:

```bash
find "$ENGINEERING_PATH" -type f -name '*.md' -print | sort

find "$ENGINEERING_PATH" -type d \( \
  -iname 'workplan' -o \
  -iname 'workplans' -o \
  -iname 'projects' -o \
  -iname 'incidents' -o \
  -iname 'postmortems' \
\) -print | sort
```

Do not skip nested service, platform, shared-library, archived, or cross-team folders merely because their repository names are not known in advance.

#### Pass 2 — Find workplans and design artifacts

Search by both path/filename and content. Workplans often contain an `index.md` that links to the PRD, technical specification, alternatives, rollout notes, or implementation status.

```bash
find "$ENGINEERING_PATH" -type f -name '*.md' \( \
  -ipath '*/workplans/*' -o \
  -iname '*workplan*' -o \
  -iname 'prd.md' -o \
  -iname 'tech-spec.md' -o \
  -iname 'tech-spec-*.md' -o \
  -iname '*technical-spec*' -o \
  -iname '*design*' -o \

From cristiano-pacheco/ai-tools, MIT.

More from cristiano-pacheco/ai-tools