docs(skills): split SKILL.md references into cli-commands / records / workflows#9
Conversation
… workflows - SKILL.md trimmed; details moved into per-topic reference pages. - references/watchers.md removed (content split across new pages). - references/cli-commands.md, records.md, workflows.md added. - references/mcp-tools.md updated to match the new layout. - example/pubspec.lock refreshed.
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the fluttersdk_telescope skill documentation into focused reference pages for MCP tools, CLI commands, record shapes, and common workflows, while removing the older watcher-specific reference.
Changes:
- Expands
SKILL.mdwith higher-level agent guidance and links to new reference files. - Adds focused
cli-commands.md,records.md, andworkflows.mdreferences, and rewritesmcp-tools.md. - Refreshes the example lockfile for updated package versions.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
skills/fluttersdk-telescope/SKILL.md |
Updates skill metadata, core laws, workflows, tool surface, and reference links. |
skills/fluttersdk-telescope/references/workflows.md |
Adds common telescope and dusk workflow guidance. |
skills/fluttersdk-telescope/references/watchers.md |
Removes the old watcher-focused reference page. |
skills/fluttersdk-telescope/references/records.md |
Adds per-record JSON field reference. |
skills/fluttersdk-telescope/references/mcp-tools.md |
Rewrites MCP tool schemas, envelopes, examples, and semantics. |
skills/fluttersdk-telescope/references/cli-commands.md |
Adds CLI command flags, outputs, and behavior reference. |
example/pubspec.lock |
Refreshes locked versions for the example app. |
| matches nothing, returning an empty array. No error envelope is | ||
| emitted; the handler always returns `ServiceExtensionResponse.result`. |
There was a problem hiding this comment.
Fixed in 365e68b. references/mcp-tools.md:443-449 (renumbered after the diff) now documents the lenient behavior: an unknown level resolves to -1 via indexOf, and every captured level satisfies actual >= -1, so the whole buffer is returned. Implementation tightening is left for a follow-up PR with tests.
| | HTTP | `telescope_requests` | `telescope:requests` | Outbound HTTP via any installed `TelescopeHttpAdapter` (Magic's `MagicHttpFacadeAdapter`, vanilla `DioHttpAdapter`, custom). Raw `dart:io HttpClient` is invisible. | | ||
| | Logs | `telescope_tail` | `telescope:tail` | Every `package:logging` Logger call. `LogWatcher` enables `hierarchicalLoggingEnabled = true` and sets `Logger.root.level = Level.ALL`, so nothing is filtered at capture. | | ||
| | Exceptions | `telescope_exceptions` | (MCP only) | Uncaught exceptions only. Carries `exceptionType`, `message`, `time`, optional `stackTrace`, `isolate`. | | ||
| | Dumps | `telescope_dumps` | (MCP only) | Every `debugPrint` call (global override). `print()` is also routed through `debugPrint` in Flutter, so `print("...")` lands here too. `dart:io stdout.write` does not. | |
There was a problem hiding this comment.
Fixed in 365e68b. SKILL.md Section 2 Dumps row now states plain Dart print(...) does NOT route through debugPrint and is therefore invisible to telescope_dumps; callers must use debugPrint(...) to be captured.
| `print("...")` and `debugPrint("...")` both produce records here; raw | ||
| `dart:io stdout.write` does not. |
There was a problem hiding this comment.
Fixed in 365e68b. references/records.md DumpRecord notes corrected: only debugPrint("...") produces a record, plain Dart print("...") is invisible to telescope_dumps.
| prior implementation. Flutter's own `print(...)` routes through | ||
| `debugPrint` in debug builds, so plain `print("...")` lands here too. | ||
| `dart:io stdout.write` and `stderr.write` do not. |
There was a problem hiding this comment.
Fixed in 365e68b. references/mcp-tools.md telescope_dumps Capture surface paragraph corrected: only calls that go through the debugPrint callback are captured; plain Dart print(...) is invisible.
Copilot review on #9 flagged two doc inaccuracies that disagreed with the implementation in lib/. 1. DumpWatcher only overrides the global `debugPrint` callback (see lib/src/watchers/dump_watcher.dart). Plain Dart `print()` does not route through `debugPrint`, so it never reaches the dumps buffer. Three places that claimed `print()` lands in `telescope_dumps` are fixed: - SKILL.md table row for Dumps in Section 2. - references/records.md DumpRecord notes. - references/mcp-tools.md telescope_dumps Capture surface paragraph. 2. `TelescopeStore._meetsLevel` uses `order.indexOf(min.toLowerCase())` which returns -1 for an unknown level name; any captured level then passes the `actual >= min` check (every valid index is >= -1). The handler therefore returns the WHOLE buffer on an invalid `level`, not the previously-documented empty array. references/mcp-tools.md Bad-input-is-silent bullet updated to match the implementation.
|
Thanks @copilot, both issues are valid. Fixed in 365e68b: 1.
2. Invalid Choosing to update the doc rather than tighten the implementation: making the level filter strict is a behavior change that needs its own PR with tests (and would risk surprising existing callers that pass bogus level strings). |
|
@anilcancakir I've opened a new pull request, #12, to work on those changes. Once the pull request is ready, I'll request review from you. |
Summary
Reorganizes the
skills/fluttersdk-telescope/reference pages so each topic has a focused file.Changes
SKILL.mdtrimmed; topic detail moved into per-area reference pages.references/watchers.mdremoved (content redistributed).references/cli-commands.md,records.md,workflows.mdadded.references/mcp-tools.mdupdated to match the new layout.example/pubspec.lockrefreshed.Notes
Skills sync is per Golden Rule 2 in
CLAUDE.md. No behavioral change inlib/.