From hiivmind-documentation-profile
Build or refresh a documentation-ready profile of a large software package before writing docs. Use when documentation needs to cover many modules, subpackages, public APIs, backend architecture, maintainers, users, contributors, or marketing audiences; when raw code is too large or uneven for direct LLM documentation; or when incremental documentation updates must track the last profiled git commit hash.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hiivmind-documentation-profile:package-documentation-profileThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create an auditable package profile first, then derive documentation from that profile. The profile is a stocktake of modules, APIs, architecture roles, audience relevance, and provenance. It is not prose documentation until the user explicitly asks for docs synthesis.
Create an auditable package profile first, then derive documentation from that profile. The profile is a stocktake of modules, APIs, architecture roles, audience relevance, and provenance. It is not prose documentation until the user explicitly asks for docs synthesis.
Input: package_path or repository root. Optional: existing profile directory, audience lenses, include/exclude globs, output path.
Output: Profile manifest, per-module profiles, audience facet maps, coverage report, and update notes.
External references:
references/profile-schema.md|references/classification-rubric.md|references/update-algorithm.md
Every phase that depends on an external reference must read the file and prove it was loaded before executing phase logic.
LOAD_AND_VERIFY(path, proof):
content = Read(path)
IF content IS empty OR unreadable:
HALT "Cannot proceed: {path} not found or empty"
extracted = proof(content)
DISPLAY "Loaded {path}: {extracted}"
Before writing output, verify:
source.git.current_hash.previous_hash, current_hash, and changed scopes.| Phase | Description | Runs |
|---|---|---|
| 0: Intent | Determine mode, scope, audiences, output location | Always |
| 1: Baseline | Capture repository metadata, git hash, package layout | Always |
| 2: Discover | Inventory modules, public exports, tests, examples, docs | Always |
| 3: Classify | Assign module role, stability, audience, documentation priority | Always |
| 4: Profile | Write or refresh per-module profile records | Always |
| 5: Facets | Build audience-specific maps from the module profiles | Always |
| 6: Coverage | Detect missing, stale, ambiguous, or undocumented areas | Always |
| 7: Update Manifest | Persist provenance and incremental update metadata | Always |
| 8: Synthesize Docs | Produce docs outlines or prose from the profile | Only if requested |
Runs before scanning large code areas.
INTENT():
mode = choose one:
- "initial-profile" # no trusted profile exists
- "incremental-refresh" # profile exists; update from last hash
- "docs-synthesis" # profile exists; write docs from it
audiences = choose any:
- users
- maintainers
- contributors
- backend-architecture
- extension-authors
- executives-marketing
- broader-hype
scope = determine:
- repository root or package root
- output profile directory
- include/exclude globs
- whether tests/examples/docs are included as evidence
IF mode == "docs-synthesis" AND no profile exists:
REPORT "No profile found; run initial-profile first."
STOP
Default output path if the user does not specify one:
docs/package-profile/
Do not overwrite hand-written documentation unless the user explicitly asks for docs synthesis.
BASELINE(package_path):
LOAD_AND_VERIFY("references/profile-schema.md",
proof: content contains "manifest.json" and "modules/")
current_hash = git rev-parse HEAD
branch = git branch --show-current
status = git status --short
IF status is not empty:
record working_tree_dirty = true
record changed files separately from committed hash provenance
detect package manager and language:
- pyproject.toml, setup.cfg, package.json, Cargo.toml, go.mod, etc.
detect package roots:
- src layout
- top-level package directories
- namespace packages
detect existing documentation:
- README, docs/, examples/, notebooks, design notes
write baseline into computed.repo
The commit hash is a provenance anchor, not a claim that the working tree is clean. If dirty files are present, keep them visible in the manifest.
DISCOVER(package_path):
discover source files from include/exclude globs
group files into modules using language-native boundaries
discover public API signals:
- __init__ exports, __all__, package entrypoints
- public classes/functions/types
- CLI commands, plugins, routes, tasks, schemas
discover evidence:
- tests that reference each module
- examples that use each module
- docs that mention each module
- config files that wire each module
FOR each module:
computed.modules[module_id].files = source files
computed.modules[module_id].public_symbols = symbols
computed.modules[module_id].evidence = tests/examples/docs/config
Prefer language-aware tools when available: LSP, package metadata, AST parsers, and test discovery. Use text search for comments, docs, config keys, and framework conventions.
CLASSIFY(computed):
LOAD_AND_VERIFY("references/classification-rubric.md",
proof: content contains module roles and audience lenses)
FOR module IN computed.modules:
module.role = classify primary role:
public-api | api-builder | protocol | backend | model | orchestration |
io | integration | test-support | docs-example | legacy | experimental
module.visibility = classify:
public | semi-public | internal | private
module.audiences = classify relevance:
users | maintainers | contributors | backend-architecture |
extension-authors | executives-marketing | broader-hype
module.stability = classify:
stable | evolving | experimental | deprecated | unknown
module.doc_priority = classify:
essential | useful | reference-only | internal-note | skip-with-reason
module.confidence = high | medium | low
IF confidence == low:
add open_question with evidence gap
Classifications must be evidence-based. Record the evidence path, symbol, test, doc, or import relationship that supports each non-obvious classification.
PROFILE(computed, output_path):
LOAD_AND_VERIFY("references/profile-schema.md",
proof: content contains "module-profile.json")
FOR module IN computed.modules:
profile = {
id,
path,
summary,
role,
visibility,
stability,
audiences,
public_api,
key_classes,
key_functions,
dependencies,
dependents,
extension_points,
lifecycle_notes,
documentation_hooks,
examples,
tests,
risks,
open_questions,
evidence,
source_hash
}
write module profile to:
output_path + "/modules/" + safe_module_id + ".json"
preserve user-authored fields if refreshing an existing profile:
- notes
- editorial_status
- owner
- manual_summary
Keep summaries short and factual. Avoid marketing language in module profiles; marketing and positioning belong in facet maps or docs synthesis.
FACETS(computed, output_path):
FOR audience IN intent.audiences:
facet = build ordered view from module profiles:
- concepts this audience needs first
- modules relevant to those concepts
- public APIs and examples to feature
- internals to hide, footnote, or reserve for maintainer docs
- unresolved documentation questions
write output_path + "/facets/" + audience + ".json"
Required default facets:
The broader-hype facet must still cite real module evidence. Do not invent claims.
COVERAGE(computed):
missing_profiles = discovered modules without profiles
stale_profiles = profiles whose source_hash differs from current_hash or changed files
orphan_profiles = profiles for modules no longer found
public_without_user_facet = public modules absent from users facet
internal_without_maintainer_facet = internal architecture modules absent from maintainers facet
low_confidence = modules with confidence == low
write coverage report:
output_path + "/coverage.md"
IF missing_profiles is non-empty:
fail verification unless each has an ignore reason
Use coverage to guide documentation planning. Do not hide gaps in generated prose.
MANIFEST(computed, output_path):
LOAD_AND_VERIFY("references/update-algorithm.md",
proof: content contains "previous_hash" and "changed_scopes")
manifest = {
profile_version,
generated_at,
source: {
root,
git: {
previous_hash,
current_hash,
branch,
working_tree_dirty
}
},
scope,
audiences,
counts,
changed_scopes,
ignored_paths,
profile_files
}
write output_path + "/manifest.json"
The manifest is the entry point for future refreshes. If it is missing or invalid, fall back to initial profiling.
Run only when the user asks to write documentation from the profile.
SYNTHESIZE(intent, output_path):
read manifest and relevant facet files
choose document type:
- README section
- user guide
- API reference outline
- maintainer architecture guide
- contributor onboarding
- marketing narrative
- documentation roadmap
write from profile evidence, not raw code alone
include unresolved questions where they affect accuracy
keep audience boundaries explicit
When writing docs, prefer generating an outline first for large projects. For high-level narratives, connect claims back to module evidence or examples.
Use this path when a profile manifest already exists.
INCREMENTAL_REFRESH(package_path, profile_path):
LOAD_AND_VERIFY("references/update-algorithm.md",
proof: content contains REFRESH_SCOPE)
manifest = read profile_path + "/manifest.json"
previous_hash = manifest.source.git.current_hash
current_hash = git rev-parse HEAD
changed_files = git diff --name-only previous_hash current_hash
changed_uncommitted = git status --short
changed_scopes = map files to modules and facets
FOR module IN changed_scopes.modules:
rerun DISCOVER, CLASSIFY, PROFILE for module and local dependents
rerun FACETS for affected audiences
rerun COVERAGE
rerun MANIFEST
If the previous hash is unavailable locally, record that incremental ancestry could not be verified and run a conservative full refresh.
End every run with:
Profile path: <path>
Source hash: <current_hash>
Mode: <initial-profile|incremental-refresh|docs-synthesis>
Modules discovered: <n>
Modules profiled: <n>
Facets written: <list>
Coverage gaps: <n>
Changed scopes: <list or none>
Next recommended documentation work: <short list>
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.
npx claudepluginhub hiivmind/hiivmind-documentation-profile --plugin hiivmind-documentation-profile