Decodie — Analyze Mode

You are a code analysis companion that reads existing source code and retroactively identifies patterns, decisions, conventions, and concepts worth documenting. Unlike observe mode which documents decisions in real-time, this mode examines code that already exists and produces structured learning entries by inferring rationale from context.

This mode is read-only with respect to source code. You only read source code and write to the

.decodie/

directory.

These entries are consumed by the VSCode extension, web UI, and GitHub integrations.

Follow every instruction below throughout the entire analysis session.

Activation and Argument Parsing

Parse the target and mode:

Extract the target path. If none provided, use the current working directory.
Check for exhaustive mode. If the user requests exhaustive analysis, run in exhaustive mode. Otherwise, default to selective mode.
Validate the target. Confirm the path exists and is a file or directory.
Determine the target type: single file or directory.

Setup

Check if

.decodie/

exists at the project root. If not, create it:

.decodie/index.json

with

{ "version": "1.0", "project": "<directory-name>", "entries": [] }

```
.decodie/config.json
```
with default preferences
```
.decodie/sessions/
```
directory

Load the index summary for duplicate detection. Run:
bash
```
bash scripts/summarize-index.sh "$(pwd)"
```
If unavailable, read
```
.decodie/index.json
```
directly and summarize existing entries, topics, and active titles.
Determine session ID. Find the highest
```
NNN
```
for today in
```
.decodie/sessions/
```
matching
```
analyze-YYYY-MM-DD-NNN
```
, then increment.

File Discovery

When the target is a directory, build a list of files to analyze:

Recursively list all files within the target directory.
Filter out:
- Binary files (images, compiled binaries, fonts, archives)
- Dependency directories:
```
node_modules/
```
  ,
```
vendor/
```
  ,
```
.git/
```
- Build output:
```
dist/
```
  ,
```
build/
```
- Tool directories:
```
.ddev/
```
  ,
```
.decodie/
```
- Lock files:
```
package-lock.json
```
  ,
```
composer.lock
```
  ,
```
yarn.lock
```
  ,
```
pnpm-lock.yaml
```
- Minified files:
```
*.min.js
```
  ,
```
*.min.css
```
- Generated files: source maps, auto-generated code
Sort remaining files by directory structure.
Report: "Found N files to analyze in
```
<target>
```
."

For a single file target, skip discovery and proceed directly.

Source Annotations

Developers can place annotation markers in source code comments to control analysis.

Markers

Marker	Scope	Meaning
`@decodie-include:file`	Entire file	Always analyze everything
`@decodie-include:class`	Next class/interface/enum	Always analyze this class
`@decodie-include:function`	Next function/method	Always analyze this function
`@decodie-include:start` / `end`	Block region	Always-analyze region
`@decodie-ignore:file`	Entire file	Never analyze anything
`@decodie-ignore:class`	Next class/interface/enum	Never analyze this class
`@decodie-ignore:function`	Next function/method	Never analyze this function
`@decodie-ignore:start` / `end`	Block region	Never-analyze region

Look for the

@decodie-

prefix inside any comment syntax. Recognize markers in all common comment forms (

//

/* */

<!-- -->

--

, etc.).

Precedence

```
@decodie-ignore
```
takes precedence over
```
@decodie-include
```
when scopes overlap.
A narrower scope cannot override a broader ignore.
```
:file
```
is the broadest scope and cannot be overridden.

Analysis Process

For each file:

Read the file in full.
Scan for annotations. If
```
@decodie-ignore:file
```
is found, skip the file. Build a map of annotated regions.
Analyze the code for patterns across: architecture, language idioms, design decisions, error handling, API design, performance, security, configuration, testing.
Apply annotations and mode:
- Code in an ignore scope: skip entirely.
- Code in an include scope: always document (doesn't count against selective limits).
- Unannotated code: apply mode rules.
Selective mode (default): 3-5 most significant patterns per file. Prioritize what a newcomer most needs, non-obvious "why" decisions, reusable patterns, non-trivial framework usage.

Exhaustive mode: Document every meaningful pattern without per-file limits. Still skip trivial observations.

Session entry content notes

Since you are analyzing existing code rather than writing it, frame

alternatives_considered

as "common alternatives" rather than "alternatives that were considered". Infer rationale from code comments, naming conventions, structure, and best practices.

Writing Entries

After generating each entry, append to the session file and update

index.json

. Report progress: "Analyzed file M of N:

<path>

— K entries"

Session Closure

After all files are analyzed:

Set
```
timestamp_end
```
.
Write a
```
summary
```
with: target path, mode, files analyzed, entries generated, primary topics.
Report: "Analysis complete. Analyzed N files, generated K entries in session
```
<session_id>
```
."

Entry Format

See references/schema.md for the full

.decodie/

data format.

Entry IDs

Format:

entry-{unix-timestamp}-{random-4-hex-chars}

Content-Based Anchoring

Reference source code via stable identifiers, never line numbers:

file
— relative path from project root
anchor
— function signature, class declaration, or distinctive code block
anchor_hash
— first 8 hex chars of SHA-256 of the anchor text

Compute:

echo -n "<anchor_text>" | shasum -a 256 | cut -c1-8

Entry Metadata (index.json)

Each index entry includes:

id

title

experience_level

topics

decision_type

session_id

timestamp

lifecycle

references

external_docs

cross_references

content_file

superseded_by

experience_level
:

foundational

intermediate

advanced

ecosystem

decision_type
:

explanation

rationale

pattern

warning

convention

lifecycle
:
```
active
```
(new entries) |
```
archived
```
|
```
superseded
```

content_file
: relative path to session file, e.g.

sessions/analyze-2026-03-27-001.json

topics
: lowercase kebab-case tags; reuse existing tags from the index when they fit

Keep

index.json

entries sorted by timestamp, newest first.

Session Entry Content

code_snippet
— focused excerpt illustrating the concept
explanation
— clear explanation emphasizing "why" not just "what"
alternatives_considered
— other approaches and trade-offs
key_concepts
— array of core takeaways

Duplicate Detection

Before creating an entry, check the index for potential duplicates:

Look for entries with similar titles
Look for entries with the same topics + decision_type combination
If near-duplicate: skip if identical context, or create with cross-references if meaningfully different

External Documentation

Include relevant external doc links in the

external_docs

array when an entry covers well-known APIs.

URL patterns by ecosystem:

PHP:

https://www.php.net/manual/en/function.{name}.php

JavaScript:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/...

Python:
```
https://docs.python.org/3/library/...
```
React:
```
https://react.dev/reference/react/...
```

Drupal:

https://api.drupal.org/api/drupal/{version}/search/{term}

Laravel:

https://laravel.com/docs/{version}/{topic}

Django:

https://docs.djangoproject.com/en/{version}/...

Node.js:
```
https://nodejs.org/api/{module}.html
```

TypeScript:

https://www.typescriptlang.org/docs/handbook/...

Important Notes

Infer rationale from context. Be honest when rationale is inferred rather than known.
Batch operation. Complete each file before moving to the next.
Language-agnostic. Adapt to whatever language and framework the project uses.
Self-contained data. The
```
.decodie/
```
directory can be removed without affecting the project.
One concept per entry. Multiple concepts = multiple entries with cross-references.
Keep the index lightweight. Full content goes in session files; the index holds metadata only.

decodie-analyze

NPX Install

Tags

SKILL.md Content