topoteretes/cognee / .agents/skills/docstring-author
docstring-author
VerifiedWrite or improve Python docstrings on the ten files in pilot_files.md, making supported Cognee benefits and connections between capabilities explicit. Pass 1 of the docstring pilot; a separate critic verifies the patch and writes the claim ledger.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.7 KB |
| pilot_files.md | markdown | 4.2 KB |
pilot_files.md
View on GitHub# Docstring pilot — the ten selected files
This file is the **allowlist**, not a suggestion. `tools/check_docstring_pilot_path.py`
parses the table below and rejects any `path` that is not in it, so
`.github/workflows/docstring_pilot.yml` cannot be pointed at a file the pilot did not
choose. The `docstring-author` skill beside it reads the same table, so the allowlist and
the author's instructions cannot drift apart. Adding a row is a human decision made in a
reviewed PR — the automation never extends this list.
It lives under `docstring-author` rather than somewhere neutral because the author is the
only agent that reads it: the reasons below say what each file was picked to demonstrate,
which is the expected answer, so `docstring-critic` is deliberately kept away from them.
Selection principle: files a developer or a coding agent is likely to open while
*evaluating or integrating* cognee — package entrypoints, public SDK functions, core
abstractions, extension points, and the enum whose members users pass as arguments.
Five files have weak or missing docstrings; five are already documented. Both groups test
whether supported caller benefits are explicit, including what each capability unlocks
and which conditions apply. The critic checks truthfulness and tone; existing coverage
alone does not show that the value is clear.
Docstring counts below were re-measured on `dev` at `3645f2b` and will drift as the
repo moves. They record why each file was picked, not a contract.
## Weak or incomplete surfaces
| File | Why it is a high-value docstring surface |
|---|---|
| `cognee/context_global_variables.py` | Imported by 75 modules and the place that decides whether a call runs against an isolated per-dataset graph and vector database, yet it has no module docstring and its two access-control gates (`multi_user_support_possible`, `backend_access_control_enabled`) are undocumented. The inline comment beside the gate says an unsupported backend disables access control, while the code raises `OSError` — a file where paraphrasing a comment instead of reading the code produces a false docstring. |
| `cognee/modules/search/types/SearchType.py` | The enum whose twenty-one members are the `query_type` value users pass to `search()` and `recall()`, with no module, class, or member documentation — so choosing between `HYBRID_COMPLETION` and `GRAPH_COMPLETION` today means reading the retriever implementations. |
| `cognee/shared/data_models.py` | Holds `KnowledgeGraph`, `Node`, and `Edge`, the shapes every LLM extraction call fills in and the baseline a custom `graph_model` is written against, yet 28 of its 41 public models are undocumented and several that are documented are tautological (`"""Knowledge graph."""`). |
| `cognee/infrastructure/llm/LLMGateway.py` | The single seam every LLM call in cognee passes through and the place a new provider is wired in, with all three public gateway methods (`acreate_structured_output`, `create_transcript`, `transcribe_image`) undocumented. |
| `cognee/modules/pipelines/operations/pipeline.py` | The orchestrator that `add`, `cognify`, and `memify` all funnel into; it has no module docstring and its public `run_pipeline_per_dataset` is undocumented, leaving the per-dataset locking and concurrency contract invisible to anyone writing a custom pipeline. |
## Already-documented surfaces
| File | Why it is a high-value docstring surface |
|---|---|
| `cognee/api/v1/add/add.py` | Public ingestion entrypoint: clarify the loading, storage, and permission work it handles for callers, and where further processing is needed. |
| `cognee/api/v1/remember/remember.py` | Primary memory entrypoint: explain which processing steps it combines and when to use dataset or session memory. |
| `cognee/infrastructure/databases/graph/graph_db_interface.py` | Graph backend extension point: explain what an adapter lets callers reuse and which operations and capabilities it must provide. |
| `cognee/infrastructure/engine/models/DataPoint.py` | Graph-node base class: explain how identity, indexing, and versioning choices affect the custom models callers build. |
| `cognee/modules/retrieval/base_retriever.py` | Retrieval extension point: show what the shared retrieval flow handles and what a custom retriever must supply. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |