# Shadow Frog Update

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-microsoft-shadowfrog-shadow-frog-update`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [microsoft](https://github.com/microsoft)
- **Source:** https://github.com/microsoft/ShadowFrog/tree/main/skills/shadow-frog-update

## Install

```sh
agentstack add skill-microsoft-shadowfrog-shadow-frog-update
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ShadowFrog Update

Updates `.shadow/` from two sources: code changes (git diff) and conversational
knowledge (what the user said during the session). Prerequisite: `.shadow/` exists.

## Triggers

1. Hook reminder: `preToolUse` injects a staleness warning when
   `.shadow/_meta/state.json#last_commit` differs from HEAD. The hook
   only reminds — it does NOT auto-run update.
2. Manual: user invokes `/shadow-frog-update`

## Phase 1: Detect Changes

```bash
# Read last_commit defensively: it may be missing, or the literal "none"
# when init ran without git (e.g. inside a container). `git diff none HEAD`
# would abort with "fatal: bad revision 'none'", and a missing key would
# make $LAST_COMMIT empty so `git diff HEAD` silently reports the wrong set.
LAST_COMMIT=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('last_commit','none'))" /dev/null || echo "none")
if git rev-parse --verify "$LAST_COMMIT" >/dev/null 2>&1; then
    git diff --name-only "$LAST_COMMIT" HEAD   # committed changes since last update
else
    echo "WARNING: state.json has no usable last_commit — falling back to a full re-scan."
fi
git diff --name-only HEAD                       # uncommitted changes
git diff --name-only --cached                   # staged changes
```

Categorize: modified, added, deleted, renamed.

## Phase 2: Update Per-File Shadows (Symbol-Level)

For each changed file, update its shadow at the symbol level:

- **Added symbols** → add new `##` section
- **Removed symbols** → mark section as `REMOVED`, keep discoveries for history
- **Renamed symbols** → update heading, preserve discoveries
- **Modified symbols** → check if discoveries still hold

Lightweight update (auto/hook): re-extract symbols, update headings, flag stale.
Deep update (manual/dream): read diffs, generate new discoveries, verify existing ones.

## Phase 3: Capture Conversational Knowledge

When the user shares knowledge during the session, write it immediately.
Do not batch for later.

Signals to capture:

| Signal | Example | Category |
|--------|---------|----------|
| Warning | "Don't change the retry logic, it's subtle" | warning |
| Design intent | "We use this pattern because the API is unreliable" | intent |
| History | "We tried caching here but it caused stale reads" | history |
| Gotcha | "This looks wrong but matches the tax authority spec" | warning |
| Deprecation | "This module is being replaced by v2/" | intent |
| Contract | "The 30s timeout matches our SLA" | contract |
| Convention | "Always use the helper in utils.py, not raw SQL" | convention |

Write as:
```markdown
- 
  _(verified, source: user)_
```

For knowledge emerging from collaborative work (debugging, refactoring, test failures):
```markdown
- 
  _(verified, source: interaction)_
```

Anchor to the specific `file::symbol`. `source: user` and `source: interaction`
are always `verified`.

### Auto-Placement

Users will not specify where to store their knowledge. You must find the
correct location. Procedure:

1. Parse the user's statement for code references — file names, function names,
   class names, module names, variable names, error messages, CLI flags.
2. If the knowledge is a **project-wide preference or convention** with no code
   references (e.g., "always use snake_case", "no backward compatibility",
   "prefer small PRs") → write to `_prefs.md`.
3. If explicit references found → look up those `file::symbol` paths in
   `_index.md` and the corresponding shadow files.
4. If no explicit references → use context:
   - What file is the user currently viewing or editing?
   - What files were recently modified in this session?
   - Search shadow files: `grep -rl "" .shadow/ --include="*.md"`
5. If multiple candidate locations → pick the most specific symbol that the
   knowledge applies to. Prefer a single `file::symbol` over file-level.
6. If the knowledge spans 3+ files → create a `_cross/.md`
   entry and add back-pointers to each involved file's `## Cross-References`.
   For 2-file discoveries, use per-file entries with `Also involves:` instead.
7. If no matching location exists (e.g., the user mentions a concept not yet in
   the shadow) → place at the file-level `## File-Level` section of the most
   relevant file, or create a new `_cross/` entry for repo-wide knowledge.

Never ask the user "where should I put this?" — always resolve placement yourself.

## Phase 4: Extract Session Insights

At session end or manual trigger, review the session for:
1. Files modified and why
2. Patterns revealed by the changes
3. Unrecorded conversational knowledge (user statements not yet shadowed)
4. Cross-cutting discoveries (create in `_cross/.md` if 3+ files involved)

## Phase 5: Handle Structural Changes

Added files:
1. Check `.shadow/.shadowignore` — skip if the file matches an ignore pattern
2. Create `.shadow//.md` with symbol-organized template
3. Add `## Cross-References` section
4. Add to `_index.md`

Deleted files:
1. Add `ORPHANED` marker to shadow header
2. Keep shadow (discoveries explain history)
3. Mark `[REMOVED]` on any `_cross/` refs pointing to this file
4. Update `_index.md`

Renamed files:
1. Move `.shadow/.md` to `.shadow/.md`
2. Update all `_cross/` `**Refs**:` entries (old path → new path)
3. Update all `Also involves:` in other per-file shadows
4. Update `_index.md`
5. Preserve all discoveries

## Phase 6: Verify and Dedup

Follow the dedup and writing rules in `/shadow-frog` — read before
write, merge or update existing entries, fix bad format in place.

**Verify exploration discoveries** using the observe-based or do-based
methods in `/shadow-frog` § Verification. `source: user` and
`source: interaction` → always `verified`; only re-verify if the
underlying code changes.

## Phase 7: Verify Reference Integrity

Check the five core invariants (full 7-invariant set in `/shadow-frog`):
- Every `_cross/.md` ref has a back-pointer in per-file `## Cross-References`
- Every `## Cross-References` entry has a corresponding `_cross/.md`
- No duplicate cross-cutting filenames
- All `Also involves:` use `file::symbol` notation
- No duplicate discoveries (same behavioral claim at same symbol)

Repair any violations before proceeding.

## Phase 8: Update Metadata

Preserve `dream_cycles_completed` from the existing state — only `dream-reconcile.py` increments it.

```json
{
  "version": 1,
  "initialized_at": "",
  "last_update_at": "",
  "last_commit": "",
  "last_update_type": "init|auto|manual|dream|meditate",
  "total_files": N,
  "total_symbols": N,
  "total_discoveries": N,
  "dream_cycles_completed": 
}
```

Refresh `_index.md` with current counts.

## Discovery Writing Rules

See `/shadow-frog` § Discovery Format for the verbatim per-file,
cross-cutting, and preference formats. Rules to keep in mind during
update sessions:

- Be behavioral: "silently returns None on expired tokens" not "handles token expiration"
- `source: user` and `source: interaction` → always `verified`, use user's own words
- `source: exploration` → mark `uncertain` unless verified by code reading or tests
- If 3+ files involved → create in `_cross/.md` instead, add back-pointers
- If project-wide preference with no file reference → write to `_prefs.md`
- Slug naming: kebab-case derived from title (e.g., "Token expiry config split" → `token-expiry-config-split.md`)

## Staleness Rules

- Symbol modified → check if discovery still holds
- Symbol renamed → move discoveries to new heading
- Symbol removed → mark section `REMOVED`, keep discoveries
- `source: user` discoveries → only mark stale if symbol completely removed

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [microsoft](https://github.com/microsoft)
- **Source:** [microsoft/ShadowFrog](https://github.com/microsoft/ShadowFrog)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-microsoft-shadowfrog-shadow-frog-update
- Seller: https://agentstack.voostack.com/s/microsoft
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.