Update to RoboSystems

{
  "name": "sec-filing-analysis",
  "description": "Analyze a public company from its SEC EDGAR XBRL filings on the RoboSystems `sec` graph — statements by ticker or CIK, cross-period and cross-company metric comparisons, concept-to-element resolution, and full-text search over 10-K/10-Q narrative. Use for questions like \"show me NVIDIA's income statement\", \"compare gross margin across the last eight quarters\", \"which filers mention goodwill impairment\", or any request that names a ticker, CIK, 10-K, 10-Q, or XBRL concept.",
  "included_files": [],
  "skill_md_contents": "---\nname: sec-filing-analysis\ndescription: >-\n  Analyze a public company from its SEC EDGAR XBRL filings on the RoboSystems `sec`\n  graph — statements by ticker or CIK, cross-period and cross-company metric\n  comparisons, concept-to-element resolution, and full-text search over 10-K/10-Q\n  narrative. Use for questions like \"show me NVIDIA's income statement\", \"compare\n  gross margin across the last eight quarters\", \"which filers mention goodwill\n  impairment\", or any request that names a ticker, CIK, 10-K, 10-Q, or XBRL concept.\n---\n\n# SEC filing analysis on the `sec` graph\n\nThe `sec` graph is a curated, read-only knowledge graph of public-company XBRL\nfilings. There is no general ledger here and nothing to write; every tool is an\nanalytical read. Rate limits apply per plan, so prefer one well-chosen call over\nmany exploratory ones.\n\n## The ladder — cheapest tool that answers\n\n1. **`financial-statement-analysis`** — a whole statement for one company.\n   `ticker` is required on `sec`; `statement_type` is `income_statement`,\n   `balance_sheet`, `cash_flow_statement` or `equity_statement`. Without\n   `report_id` it auto-resolves the latest matching filing (`period_type`\n   `annual` → 10-K/20-F/40-F; `quarterly` → 10-Q; `instant` for balance-sheet\n   facts). Returns deduplicated consolidated facts ordered by period, plus the\n   `resolved_report`. Start here for \"show me X's statement\".\n2. **`build-fact-grid`** — *specific* elements across any mix of periods and\n   entities. Use `canonical_concepts` (`revenue`, `net_income`, `total_assets`,\n   …) rather than raw qnames so cross-filer tagging differences collapse\n   (`us-gaap:Revenues` vs `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax`).\n   Set `period_type` for duration concepts, `entities` for multi-company\n   comparisons, and raise `limit` when `truncated` comes back true. This is the\n   tool for \"compare A and B\" and \"trend over N periods\".\n3. **`resolve-element`** — map a concept in words to the qnames actually used,\n   with fact counts and a ready-to-run `query_hint`. Call it before writing\n   Cypher that filters on an element.\n4. **`search-documents`** — BM25 keyword search across filing narrative and\n   iXBRL disclosure sections; `semantic: true` adds vector ranking. Filter with\n   `entity`, `form_type`, `fiscal_year`, `section` (`item_1a`, `item_7`, …) or\n   `element` (find disclosures carrying a given XBRL fact). Follow a hit with\n   **`get-document-section`** for the full text; iXBRL hits carry\n   `xbrl_elements` you can hand to `resolve-element` — the bridge from narrative\n   back to numbers.\n5. **`read-graph-cypher`** — when the shaped tools don't fit. Always run\n   `get-example-queries` first; the patterns below are the ones that matter.\n\n## Cypher patterns that work here\n\nConsolidated revenue for one company, cross-filer robust:\n\n```cypher\nMATCH (f:Fact {has_dimensions: false})-[:FACT_HAS_ELEMENT]->(e:Element),\n      (f)-[:FACT_HAS_ENTITY]->(ent:Entity {ticker: 'NVDA'}),\n      (f)-[:FACT_HAS_PERIOD]->(p:Period {duration_type: 'annual'})\nWHERE e.canonical_concept = 'revenue' AND f.numeric_value IS NOT NULL\nRETURN ent.ticker, e.qname, p.end_date, f.numeric_value AS revenue\nORDER BY p.end_date DESC LIMIT 10\n```\n\nA whole statement via the presentation structure — anchor on the entity, reach\n`Structure` last:\n\n```cypher\nMATCH (ent:Entity {ticker: 'NVDA'})<-[:FACT_HAS_ENTITY]-(f:Fact {has_dimensions: false})-[:FACT_HAS_ELEMENT]->(e:Element),\n      (f)-[:FACT_HAS_PERIOD]->(p:Period {duration_type: 'annual'}),\n      (fs:FactSet)-[:FACT_SET_CONTAINS_FACT]->(f),\n      (s:Structure {canonical_type: 'income_statement'})-[:STRUCTURE_HAS_FACT_SET]->(fs)\nWHERE f.numeric_value IS NOT NULL\nRETURN DISTINCT e.qname, f.numeric_value AS value, p.end_date\nORDER BY p.end_date DESC LIMIT 40\n```\n\nSegment breakdowns — flip the dimension flag:\n\n```cypher\nMATCH (f:Fact {has_dimensions: true})-[:FACT_HAS_ELEMENT]->(e:Element),\n      (f)-[:FACT_HAS_DIMENSION]->(d:Dimension)\nWHERE e.qname = 'us-gaap:Revenues' AND f.numeric_value IS NOT NULL\nRETURN d.axis_uri, d.member_uri, f.numeric_value LIMIT 10\n```\n\n## Rules of the road\n\n- **Consolidated vs dimensional.** `has_dimensions: false` is the consolidated\n  total; `true` is a segment/geography/member breakdown. Mixing them double-counts.\n- **Canonical concepts over qnames.** `Element.canonical_concept` normalizes the\n  tag zoo; `resolve-element` tells you which qnames map to it for a given filer.\n- **Periods.** Income-statement and cash-flow facts are `duration` with a\n  `duration_type`; balance-sheet facts are `instant`. Filter accordingly or you\n  get an empty or mixed result.\n- **Anchor selectively.** Lead every `MATCH` with an `Entity` or `Report`; never\n  with `Structure`, `Element` or `Period` alone. Always `LIMIT`.\n- **One `MATCH`, comma-separated patterns** for multiple relationships from the\n  same node.\n- **Numbers vs prose.** Cypher and the shaped tools answer with numbers;\n  `search-documents` answers with prose. A complete analysis usually needs both:\n  the figure, then the disclosure that explains it.\n- **Fiscal calendars vary.** NVIDIA's fiscal 2026 ended 2026-01-25. Use\n  `fiscal_year` / `fiscal_period` filters from the report's own focus rather\n  than calendar assumptions.\n\n## Worked shape\n\n\"Compare NVIDIA's gross margin across its last eight quarters\":\n\n1. `build-fact-grid` with `entity: NVDA`, `canonical_concepts:\n   [revenue, cost_of_revenue]`, `period_type: quarterly`, `limit: 40`.\n2. Compute margin per period from the returned pairs; note any period where a\n   10-K annual fact stands in for a quarter (annual filers report Q4 implicitly).\n3. If the trend needs explanation, `search-documents` with `entity: NVDA`,\n   `section: item_7`, query \"gross margin\" — and cite the section.\n"
}