[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699G289JG11BE9VRFP192X1":3,"skill-same:01M699G289JG11BE9VRFP192X1":79},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":45,"linkOnly":46,"markdownContent":47,"markdownBody":48,"frontMatter":49,"refName":50,"commitSha":51,"skillDirectory":52,"forksCount":53,"repositoryHtmlUrl":54,"repositoryHomepageUrl":6,"ownerHtmlUrl":55,"ownerBlogUrl":56,"ownerDescription":57,"updatedAt":58,"install":59,"resources":72},"01M699G289JG11BE9VRFP192X1","planning-with-files",null,"**USE THIS FOR COMPLEX TASKS.** Implements Manus-style file-based planning for multi-step tasks. Creates task_plan.md, findings.md, and progress.md in .agent_cache\u002F\u003Ctask-name>\u002F. Use when: implementing multiple APIs, refactoring modules, research tasks, or ANY task requiring >5 tool calls.","microsoft\u002Fsemantic-link-labs","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699FKMT63C17BFNH8WHZN2K",600,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplanning-with-files\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"planning with files","planning","with files","with","files","when","research","for","implementing","calls","progress","task","manus","modules","use","tool","refactoring","plan","cache","file","tasks","2026-11-10 10:12:30",false,"---\nname: planning-with-files\ndescription: \"**USE THIS FOR COMPLEX TASKS.** Implements Manus-style file-based planning for multi-step tasks. Creates task_plan.md, findings.md, and progress.md in .agent_cache\u002F\u003Ctask-name>\u002F. Use when: implementing multiple APIs, refactoring modules, research tasks, or ANY task requiring >5 tool calls.\"\n---\n\n# Planning with Files\n\nWork like Manus: Use persistent markdown files as your \"working memory on disk.\" This skill helps you plan, track, and checkpoint complex tasks that span multiple files, APIs, or sessions.\n\n## WHEN TO USE THIS SKILL\n\n**ALWAYS use this skill when:**\n- Task involves 3+ phases or steps\n- Implementing wrappers for multiple REST APIs\n- Migrating or refactoring code across multiple files\n- Research tasks requiring exploration\n- Any task requiring >5 tool calls\n- Work that may span multiple sessions\n- Tasks with dependencies between components\n\n**Skip this skill for:**\n- Simple questions or quick lookups\n- Single-file edits\n- Tasks completable in 1-2 tool calls\n\n---\n\n## The Core Principle\n\n```\nContext Window = RAM (volatile, limited)\nFilesystem = Disk (persistent, unlimited)\n\n-> Anything important gets written to disk.\n-> After ~50 tool calls, you FORGET original goals.\n-> Re-reading plan files keeps goals in your attention window.\n```\n\n---\n\n## File Structure\n\nAll planning files go in `.agent_cache\u002F\u003Ctask-name>\u002F`:\n\n```\n.agent_cache\u002F\n└── \u003Ctask-name>\u002F\n    ├── task_plan.md    # Phases, progress, decisions (YOUR ROADMAP)\n    ├── findings.md     # Research, discoveries, technical decisions\n    └── progress.md     # Session log, test results, files modified\n```\n\n### Naming Convention\n\n- Use lowercase with hyphens for `\u003Ctask-name>`\n- Be descriptive but concise\n- Examples:\n  - `.agent_cache\u002Fadd-admin-apis\u002F`\n  - `.agent_cache\u002Fmigrate-lakehouse-module\u002F`\n  - `.agent_cache\u002Fadd-direct-lake-functions\u002F`\n\n---\n\n## The 3-File Pattern\n\n| File | Purpose | When to Update |\n|------|---------|----------------|\n| `task_plan.md` | Phases, progress, current status | After each phase completes |\n| `findings.md` | Research, discoveries, decisions | After ANY discovery |\n| `progress.md` | Session log, test results, errors | Throughout session |\n\n---\n\n## Quick Start: Before ANY Complex Task\n\n```bash\n# 1. Create the planning directory\nmkdir -p .agent_cache\u002F\u003Ctask-name>\n\n# 2. Create all 3 files using templates below\n# 3. Re-read plan before major decisions\n# 4. Update after each phase completes\n```\n\n---\n\n## Critical Rules\n\n### Rule 1: Create Plan FIRST\nNever start a complex task without `task_plan.md`. **Non-negotiable.**\n\n### Rule 2: The 2-Action Rule\n> \"After every 2 view\u002Fsearch\u002Fexplore operations, IMMEDIATELY save key findings to files.\"\n\nThis prevents information from being lost as context grows.\n\n### Rule 3: Read Before Decide\nBefore major decisions, read the plan file. This pushes goals into your attention window.\n\n### Rule 4: Update After Act\nAfter completing any phase:\n- Mark phase status: `in_progress` -> `complete`\n- Log files created\u002Fmodified\n- Note any errors encountered\n\n### Rule 5: Log ALL Errors\nEvery error goes in the plan file. This builds knowledge and prevents repetition.\n\n### Rule 6: Never Repeat Failures\n```\nif action_failed:\n    next_action != same_action\n```\nTrack what you tried. Mutate the approach.\n\n---\n\n## The 3-Strike Error Protocol\n\n```\nATTEMPT 1: Diagnose & Fix\n  -> Read error carefully\n  -> Identify root cause\n  -> Apply targeted fix\n\nATTEMPT 2: Alternative Approach\n  -> Same error? Try different method\n  -> Different tool? Different pattern?\n  -> NEVER repeat exact same failing action\n\nATTEMPT 3: Broader Rethink\n  -> Question assumptions\n  -> Search for solutions (use github-repo-explore skill)\n  -> Consider updating the plan\n\nAFTER 3 FAILURES: Escalate to User\n  -> Explain what you tried\n  -> Share the specific error\n  -> Ask for guidance\n```\n\n---\n\n## Workflow: The Agent Loop\n\n```\n+--------------------------------------------+\n|  1. READ PLAN                              |\n|     - cat .agent_cache\u002F\u003Ctask>\u002Ftask_plan.md |\n|     - Understand current phase             |\n|     - Review goals                         |\n+--------------------------------------------+\n|  2. ANALYZE                                |\n|     - What's the next task?                |\n|     - Are there blockers?                  |\n|     - Do I have what I need?               |\n+--------------------------------------------+\n|  3. EXECUTE                                |\n|     - Perform ONE logical action           |\n|     - Write code to files                  |\n|     - Run tests                            |\n+--------------------------------------------+\n|  4. UPDATE FILES                           |\n|     - Log progress in progress.md          |\n|     - Save discoveries in findings.md      |\n|     - Update status in task_plan.md        |\n+--------------------------------------------+\n|  5. REPEAT                                 |\n|     - Read plan again before next phase    |\n+--------------------------------------------+\n```\n\n---\n\n## Template: task_plan.md\n\n```markdown\n# Task Plan: [Brief Description]\n\n## Goal\n[One clear sentence describing the end state]\n\n## Current Phase\nPhase 1\n\n## Guidelines\n\u003C!-- Project-specific constraints and references -->\n- Follow numpydoc style for docstrings\n- Use `@log` decorator for all public functions\n- Use `_base_api` helper for REST calls\n- Reference: [add-function skill](..\u002F..\u002F.claude\u002Fskills\u002Fadd-function\u002FSKILL.md)\n- Reference: [rest-api-patterns skill](..\u002F..\u002F.claude\u002Fskills\u002Frest-api-patterns\u002FSKILL.md)\n\n---\n\n## Phases\n\n### Phase 1: Requirements & Discovery\n- [ ] Understand user intent and scope\n- [ ] Identify files\u002FAPIs involved\n- [ ] Document findings in findings.md\n- **Status:** in_progress\n\n### Phase 2: Dependency Analysis\n- [ ] Map dependencies between components\n- [ ] Determine implementation order\n- [ ] Update plan with detailed tasks\n- **Status:** pending\n\n### Phase 3: Implementation\n- [ ] Implement each component in order\n- [ ] Write code following project conventions\n- [ ] Document decisions in findings.md\n- **Status:** pending\n\n### Phase 4: Testing\n- [ ] Write unit tests (see write-tests skill)\n- [ ] Run tests with `pytest -sv tests\u002F -k \u003Ctest_name>`\n- [ ] Document results in progress.md\n- **Status:** pending\n\n### Phase 5: Completion\n- [ ] Run code style checks: `black src\u002Fsempy_labs tests && flake8 src\u002Fsempy_labs tests`\n- [ ] Verify all checkboxes complete\n- [ ] Mark directory as done\n- **Status:** pending\n\n---\n\n## Errors Encountered\n| Error | Attempt | Resolution |\n|-------|---------|------------|\n|       |         |            |\n\n---\n\n## Decisions Made\n| Decision | Rationale |\n|----------|-----------|\n|          |           |\n```\n\n---\n\n## Template: findings.md\n\n```markdown\n# Findings & Decisions\n\n## Task\n[Brief description of the task]\n\n---\n\n## Requirements\n\u003C!-- Captured from user request -->\n-\n\n## Research Findings\n\u003C!-- Key discoveries during exploration -->\n\u003C!-- UPDATE AFTER EVERY 2 SEARCH\u002FEXPLORE OPERATIONS -->\n-\n\n## Code Patterns Found\n\u003C!-- Existing patterns in codebase to follow -->\n| Pattern | Location | Usage |\n|---------|----------|-------|\n|         |          |       |\n\n## Technical Decisions\n| Decision | Rationale |\n|----------|-----------|\n|          |           |\n\n## Files to Modify\n| File | Change |\n|------|--------|\n|      |        |\n\n## API\u002FFunction Inventory\n\u003C!-- For API wrapper tasks -->\n| Function | Source | Status |\n|----------|--------|--------|\n|          |        |        |\n\n## Issues Encountered\n| Issue | Resolution |\n|-------|------------|\n|       |            |\n\n## External References\n\u003C!-- Links to docs, GitHub repos, etc. -->\n-\n```\n\n---\n\n## Template: progress.md\n\n```markdown\n# Progress Log\n\n## Session: [DATE]\n\n### Phase 1: [Title]\n- **Status:** in_progress\n- **Started:** [timestamp]\n- Actions taken:\n  -\n- Files created\u002Fmodified:\n  -\n\n### Phase 2: [Title]\n- **Status:** pending\n- Actions taken:\n  -\n- Files created\u002Fmodified:\n  -\n\n---\n\n## Test Results\n| Test | Expected | Actual | Status |\n|------|----------|--------|--------|\n|      |          |        |        |\n\n---\n\n## Commands Run\n```bash\n# Useful commands executed during this session\n```\n\n---\n\n## Session Notes\n\u003C!-- Any observations, blockers, or context for next session -->\n```\n\n---\n\n## Project-Specific Patterns\n\n### For Semantic Link Labs API Wrapper Tasks\n\nWhen implementing REST API wrappers, include in findings.md:\n\n```markdown\n## API Analysis\n| API | Fabric Path | Power BI Path | Notes |\n|-----|-------------|---------------|-------|\n| list_items | \u002Fv1\u002Fworkspaces\u002F{id}\u002Fitems | \u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{id}\u002F... | Paginated |\n\n## Implementation Pattern\n- Use `_base_api` helper for all REST calls\n- Use `resolve_workspace_name_and_id` for workspace resolution\n- Use `_create_dataframe` for empty DataFrame initialization\n- Return `pandas.DataFrame` for list operations\n\n## Required Decorator\n- `@log` -- Enable logging and telemetry\n\n## Function Naming\n| Prefix | Use Case |\n|--------|----------|\n| `list_` | Retrieves a collection |\n| `get_` | Retrieves a single item |\n| `create_` | Creates a new resource |\n| `update_` | Modifies existing resource |\n| `delete_` | Removes a resource |\n```\n\n### For Test Writing Tasks\n\nInclude in findings.md:\n\n```markdown\n## Test Structure\n| Type | Location |\n|------|----------|\n| Unit tests | tests\u002F |\n\n## Key Patterns\n- Use `pytest.mark.parametrize` for multiple inputs\n- Mock `_base_api` for API wrapper tests\n- Use `_create_dataframe` to verify empty DataFrame structure\n- See write-tests skill for full patterns\n```\n\n---\n\n## Completion Workflow\n\nAfter finishing all work:\n\n```bash\n# 1. Verify all checkboxes are marked complete\ngrep -c \"\\[x\\]\" .agent_cache\u002F\u003Ctask-name>\u002Ftask_plan.md\ngrep -c \"\\[ \\]\" .agent_cache\u002F\u003Ctask-name>\u002Ftask_plan.md\n\n# 2. Rename directory with [done] suffix\nmv .agent_cache\u002F\u003Ctask-name> .agent_cache\u002F\u003Ctask-name>-[done]\n```\n\n---\n\n## The 5-Question Reboot Test\n\nWhen resuming work, verify you can answer:\n\n| Question | Answer Source |\n|----------|---------------|\n| Where am I? | Current phase in task_plan.md |\n| Where am I going? | Remaining phases |\n| What's the goal? | Goal statement in plan |\n| What have I learned? | findings.md |\n| What have I done? | progress.md |\n\nIf you can't answer these, read all 3 planning files before continuing.\n\n---\n\n## Read vs Write Decision Matrix\n\n| Situation | Action | Reason |\n|-----------|--------|--------|\n| Just wrote a file | DON'T read | Content still in context |\n| After 2+ searches | Write findings NOW | Before info is lost |\n| Starting new phase | Read plan\u002Ffindings | Re-orient context |\n| Error occurred | Read relevant file | Need current state |\n| Resuming after gap | Read ALL planning files | Recover state |\n| Before major decision | Read task_plan.md | Refresh goals |\n\n---\n\n## Anti-Patterns\n\n| Don't | Do Instead |\n|-------|------------|\n| Start executing immediately | Create plan file FIRST |\n| State goals once and forget | Re-read plan before decisions |\n| Hide errors and retry silently | Log errors to plan file |\n| Stuff everything in context | Store large content in files |\n| Repeat failed actions | Track attempts, mutate approach |\n| Skip testing | Always include test tasks |\n\n---\n\n## Example: Adding Admin API Wrappers\n\n### task_plan.md\n```markdown\n# Task Plan: Add Admin Workspace APIs\n\n## Goal\nImplement wrapper functions for Fabric Admin Workspace APIs in the sempy_labs.admin module.\n\n## Current Phase\nPhase 3\n\n## Guidelines\n- Use `@log` decorator on all public functions\n- Use `_base_api` helper for REST calls\n- Reference: add-function skill, rest-api-patterns skill\n\n---\n\n## Phases\n\n### Phase 1: Requirements & Discovery\n- [x] Read Fabric Admin API documentation\n- [x] Identify workspace-related endpoints\n- [x] Document in findings.md\n- **Status:** complete\n\n### Phase 2: Dependency Analysis\n- [x] Check existing workspace implementations\n- [x] Create function inventory\n- **Status:** complete\n\n### Phase 3: Implementation\n- [x] `list_workspaces`\n- [x] `get_workspace`\n- [ ] `list_workspace_access_details`\n- [ ] `update_workspace`\n- **Status:** in_progress\n\n### Phase 4: Testing\n- [ ] Write unit tests with mocks\n- [ ] Run tests\n- **Status:** pending\n\n### Phase 5: Completion\n- [ ] Run black, flake8\n- [ ] Verify all tests pass\n- **Status:** pending\n\n---\n\n## Errors Encountered\n| Error | Attempt | Resolution |\n|-------|---------|------------|\n| Pagination not working | 1 | Need uses_pagination=True in _base_api |\n```\n\n---\n\n## Related Skills\n\n| Skill | When to Use |\n|-------|-------------|\n| [add-function](..\u002Fadd-function\u002FSKILL.md) | Adding new API wrapper functions |\n| [rest-api-patterns](..\u002Frest-api-patterns\u002FSKILL.md) | REST API implementation patterns |\n| [write-tests](..\u002Fwrite-tests\u002FSKILL.md) | Writing unit tests |\n| [code-style](..\u002Fcode-style\u002FSKILL.md) | Running linters and formatters |\n| [run-tests](..\u002Frun-tests\u002FSKILL.md) | Running pytest locally |\n| [github-repo-explore](..\u002Fgithub-repo-explore\u002FSKILL.md) | Finding reference implementations |\n","# Planning with Files\n\nWork like Manus: Use persistent markdown files as your \"working memory on disk.\" This skill helps you plan, track, and checkpoint complex tasks that span multiple files, APIs, or sessions.\n\n## WHEN TO USE THIS SKILL\n\n**ALWAYS use this skill when:**\n- Task involves 3+ phases or steps\n- Implementing wrappers for multiple REST APIs\n- Migrating or refactoring code across multiple files\n- Research tasks requiring exploration\n- Any task requiring >5 tool calls\n- Work that may span multiple sessions\n- Tasks with dependencies between components\n\n**Skip this skill for:**\n- Simple questions or quick lookups\n- Single-file edits\n- Tasks completable in 1-2 tool calls\n\n---\n\n## The Core Principle\n\n```\nContext Window = RAM (volatile, limited)\nFilesystem = Disk (persistent, unlimited)\n\n-> Anything important gets written to disk.\n-> After ~50 tool calls, you FORGET original goals.\n-> Re-reading plan files keeps goals in your attention window.\n```\n\n---\n\n## File Structure\n\nAll planning files go in `.agent_cache\u002F\u003Ctask-name>\u002F`:\n\n```\n.agent_cache\u002F\n└── \u003Ctask-name>\u002F\n    ├── task_plan.md    # Phases, progress, decisions (YOUR ROADMAP)\n    ├── findings.md     # Research, discoveries, technical decisions\n    └── progress.md     # Session log, test results, files modified\n```\n\n### Naming Convention\n\n- Use lowercase with hyphens for `\u003Ctask-name>`\n- Be descriptive but concise\n- Examples:\n  - `.agent_cache\u002Fadd-admin-apis\u002F`\n  - `.agent_cache\u002Fmigrate-lakehouse-module\u002F`\n  - `.agent_cache\u002Fadd-direct-lake-functions\u002F`\n\n---\n\n## The 3-File Pattern\n\n| File | Purpose | When to Update |\n|------|---------|----------------|\n| `task_plan.md` | Phases, progress, current status | After each phase completes |\n| `findings.md` | Research, discoveries, decisions | After ANY discovery |\n| `progress.md` | Session log, test results, errors | Throughout session |\n\n---\n\n## Quick Start: Before ANY Complex Task\n\n```bash\n# 1. Create the planning directory\nmkdir -p .agent_cache\u002F\u003Ctask-name>\n\n# 2. Create all 3 files using templates below\n# 3. Re-read plan before major decisions\n# 4. Update after each phase completes\n```\n\n---\n\n## Critical Rules\n\n### Rule 1: Create Plan FIRST\nNever start a complex task without `task_plan.md`. **Non-negotiable.**\n\n### Rule 2: The 2-Action Rule\n> \"After every 2 view\u002Fsearch\u002Fexplore operations, IMMEDIATELY save key findings to files.\"\n\nThis prevents information from being lost as context grows.\n\n### Rule 3: Read Before Decide\nBefore major decisions, read the plan file. This pushes goals into your attention window.\n\n### Rule 4: Update After Act\nAfter completing any phase:\n- Mark phase status: `in_progress` -> `complete`\n- Log files created\u002Fmodified\n- Note any errors encountered\n\n### Rule 5: Log ALL Errors\nEvery error goes in the plan file. This builds knowledge and prevents repetition.\n\n### Rule 6: Never Repeat Failures\n```\nif action_failed:\n    next_action != same_action\n```\nTrack what you tried. Mutate the approach.\n\n---\n\n## The 3-Strike Error Protocol\n\n```\nATTEMPT 1: Diagnose & Fix\n  -> Read error carefully\n  -> Identify root cause\n  -> Apply targeted fix\n\nATTEMPT 2: Alternative Approach\n  -> Same error? Try different method\n  -> Different tool? Different pattern?\n  -> NEVER repeat exact same failing action\n\nATTEMPT 3: Broader Rethink\n  -> Question assumptions\n  -> Search for solutions (use github-repo-explore skill)\n  -> Consider updating the plan\n\nAFTER 3 FAILURES: Escalate to User\n  -> Explain what you tried\n  -> Share the specific error\n  -> Ask for guidance\n```\n\n---\n\n## Workflow: The Agent Loop\n\n```\n+--------------------------------------------+\n|  1. READ PLAN                              |\n|     - cat .agent_cache\u002F\u003Ctask>\u002Ftask_plan.md |\n|     - Understand current phase             |\n|     - Review goals                         |\n+--------------------------------------------+\n|  2. ANALYZE                                |\n|     - What's the next task?                |\n|     - Are there blockers?                  |\n|     - Do I have what I need?               |\n+--------------------------------------------+\n|  3. EXECUTE                                |\n|     - Perform ONE logical action           |\n|     - Write code to files                  |\n|     - Run tests                            |\n+--------------------------------------------+\n|  4. UPDATE FILES                           |\n|     - Log progress in progress.md          |\n|     - Save discoveries in findings.md      |\n|     - Update status in task_plan.md        |\n+--------------------------------------------+\n|  5. REPEAT                                 |\n|     - Read plan again before next phase    |\n+--------------------------------------------+\n```\n\n---\n\n## Template: task_plan.md\n\n```markdown\n# Task Plan: [Brief Description]\n\n## Goal\n[One clear sentence describing the end state]\n\n## Current Phase\nPhase 1\n\n## Guidelines\n\u003C!-- Project-specific constraints and references -->\n- Follow numpydoc style for docstrings\n- Use `@log` decorator for all public functions\n- Use `_base_api` helper for REST calls\n- Reference: [add-function skill](..\u002F..\u002F.claude\u002Fskills\u002Fadd-function\u002FSKILL.md)\n- Reference: [rest-api-patterns skill](..\u002F..\u002F.claude\u002Fskills\u002Frest-api-patterns\u002FSKILL.md)\n\n---\n\n## Phases\n\n### Phase 1: Requirements & Discovery\n- [ ] Understand user intent and scope\n- [ ] Identify files\u002FAPIs involved\n- [ ] Document findings in findings.md\n- **Status:** in_progress\n\n### Phase 2: Dependency Analysis\n- [ ] Map dependencies between components\n- [ ] Determine implementation order\n- [ ] Update plan with detailed tasks\n- **Status:** pending\n\n### Phase 3: Implementation\n- [ ] Implement each component in order\n- [ ] Write code following project conventions\n- [ ] Document decisions in findings.md\n- **Status:** pending\n\n### Phase 4: Testing\n- [ ] Write unit tests (see write-tests skill)\n- [ ] Run tests with `pytest -sv tests\u002F -k \u003Ctest_name>`\n- [ ] Document results in progress.md\n- **Status:** pending\n\n### Phase 5: Completion\n- [ ] Run code style checks: `black src\u002Fsempy_labs tests && flake8 src\u002Fsempy_labs tests`\n- [ ] Verify all checkboxes complete\n- [ ] Mark directory as done\n- **Status:** pending\n\n---\n\n## Errors Encountered\n| Error | Attempt | Resolution |\n|-------|---------|------------|\n|       |         |            |\n\n---\n\n## Decisions Made\n| Decision | Rationale |\n|----------|-----------|\n|          |           |\n```\n\n---\n\n## Template: findings.md\n\n```markdown\n# Findings & Decisions\n\n## Task\n[Brief description of the task]\n\n---\n\n## Requirements\n\u003C!-- Captured from user request -->\n-\n\n## Research Findings\n\u003C!-- Key discoveries during exploration -->\n\u003C!-- UPDATE AFTER EVERY 2 SEARCH\u002FEXPLORE OPERATIONS -->\n-\n\n## Code Patterns Found\n\u003C!-- Existing patterns in codebase to follow -->\n| Pattern | Location | Usage |\n|---------|----------|-------|\n|         |          |       |\n\n## Technical Decisions\n| Decision | Rationale |\n|----------|-----------|\n|          |           |\n\n## Files to Modify\n| File | Change |\n|------|--------|\n|      |        |\n\n## API\u002FFunction Inventory\n\u003C!-- For API wrapper tasks -->\n| Function | Source | Status |\n|----------|--------|--------|\n|          |        |        |\n\n## Issues Encountered\n| Issue | Resolution |\n|-------|------------|\n|       |            |\n\n## External References\n\u003C!-- Links to docs, GitHub repos, etc. -->\n-\n```\n\n---\n\n## Template: progress.md\n\n```markdown\n# Progress Log\n\n## Session: [DATE]\n\n### Phase 1: [Title]\n- **Status:** in_progress\n- **Started:** [timestamp]\n- Actions taken:\n  -\n- Files created\u002Fmodified:\n  -\n\n### Phase 2: [Title]\n- **Status:** pending\n- Actions taken:\n  -\n- Files created\u002Fmodified:\n  -\n\n---\n\n## Test Results\n| Test | Expected | Actual | Status |\n|------|----------|--------|--------|\n|      |          |        |        |\n\n---\n\n## Commands Run\n```bash\n# Useful commands executed during this session\n```\n\n---\n\n## Session Notes\n\u003C!-- Any observations, blockers, or context for next session -->\n```\n\n---\n\n## Project-Specific Patterns\n\n### For Semantic Link Labs API Wrapper Tasks\n\nWhen implementing REST API wrappers, include in findings.md:\n\n```markdown\n## API Analysis\n| API | Fabric Path | Power BI Path | Notes |\n|-----|-------------|---------------|-------|\n| list_items | \u002Fv1\u002Fworkspaces\u002F{id}\u002Fitems | \u002Fv1.0\u002Fmyorg\u002Fgroups\u002F{id}\u002F... | Paginated |\n\n## Implementation Pattern\n- Use `_base_api` helper for all REST calls\n- Use `resolve_workspace_name_and_id` for workspace resolution\n- Use `_create_dataframe` for empty DataFrame initialization\n- Return `pandas.DataFrame` for list operations\n\n## Required Decorator\n- `@log` -- Enable logging and telemetry\n\n## Function Naming\n| Prefix | Use Case |\n|--------|----------|\n| `list_` | Retrieves a collection |\n| `get_` | Retrieves a single item |\n| `create_` | Creates a new resource |\n| `update_` | Modifies existing resource |\n| `delete_` | Removes a resource |\n```\n\n### For Test Writing Tasks\n\nInclude in findings.md:\n\n```markdown\n## Test Structure\n| Type | Location |\n|------|----------|\n| Unit tests | tests\u002F |\n\n## Key Patterns\n- Use `pytest.mark.parametrize` for multiple inputs\n- Mock `_base_api` for API wrapper tests\n- Use `_create_dataframe` to verify empty DataFrame structure\n- See write-tests skill for full patterns\n```\n\n---\n\n## Completion Workflow\n\nAfter finishing all work:\n\n```bash\n# 1. Verify all checkboxes are marked complete\ngrep -c \"\\[x\\]\" .agent_cache\u002F\u003Ctask-name>\u002Ftask_plan.md\ngrep -c \"\\[ \\]\" .agent_cache\u002F\u003Ctask-name>\u002Ftask_plan.md\n\n# 2. Rename directory with [done] suffix\nmv .agent_cache\u002F\u003Ctask-name> .agent_cache\u002F\u003Ctask-name>-[done]\n```\n\n---\n\n## The 5-Question Reboot Test\n\nWhen resuming work, verify you can answer:\n\n| Question | Answer Source |\n|----------|---------------|\n| Where am I? | Current phase in task_plan.md |\n| Where am I going? | Remaining phases |\n| What's the goal? | Goal statement in plan |\n| What have I learned? | findings.md |\n| What have I done? | progress.md |\n\nIf you can't answer these, read all 3 planning files before continuing.\n\n---\n\n## Read vs Write Decision Matrix\n\n| Situation | Action | Reason |\n|-----------|--------|--------|\n| Just wrote a file | DON'T read | Content still in context |\n| After 2+ searches | Write findings NOW | Before info is lost |\n| Starting new phase | Read plan\u002Ffindings | Re-orient context |\n| Error occurred | Read relevant file | Need current state |\n| Resuming after gap | Read ALL planning files | Recover state |\n| Before major decision | Read task_plan.md | Refresh goals |\n\n---\n\n## Anti-Patterns\n\n| Don't | Do Instead |\n|-------|------------|\n| Start executing immediately | Create plan file FIRST |\n| State goals once and forget | Re-read plan before decisions |\n| Hide errors and retry silently | Log errors to plan file |\n| Stuff everything in context | Store large content in files |\n| Repeat failed actions | Track attempts, mutate approach |\n| Skip testing | Always include test tasks |\n\n---\n\n## Example: Adding Admin API Wrappers\n\n### task_plan.md\n```markdown\n# Task Plan: Add Admin Workspace APIs\n\n## Goal\nImplement wrapper functions for Fabric Admin Workspace APIs in the sempy_labs.admin module.\n\n## Current Phase\nPhase 3\n\n## Guidelines\n- Use `@log` decorator on all public functions\n- Use `_base_api` helper for REST calls\n- Reference: add-function skill, rest-api-patterns skill\n\n---\n\n## Phases\n\n### Phase 1: Requirements & Discovery\n- [x] Read Fabric Admin API documentation\n- [x] Identify workspace-related endpoints\n- [x] Document in findings.md\n- **Status:** complete\n\n### Phase 2: Dependency Analysis\n- [x] Check existing workspace implementations\n- [x] Create function inventory\n- **Status:** complete\n\n### Phase 3: Implementation\n- [x] `list_workspaces`\n- [x] `get_workspace`\n- [ ] `list_workspace_access_details`\n- [ ] `update_workspace`\n- **Status:** in_progress\n\n### Phase 4: Testing\n- [ ] Write unit tests with mocks\n- [ ] Run tests\n- **Status:** pending\n\n### Phase 5: Completion\n- [ ] Run black, flake8\n- [ ] Verify all tests pass\n- **Status:** pending\n\n---\n\n## Errors Encountered\n| Error | Attempt | Resolution |\n|-------|---------|------------|\n| Pagination not working | 1 | Need uses_pagination=True in _base_api |\n```\n\n---\n\n## Related Skills\n\n| Skill | When to Use |\n|-------|-------------|\n| [add-function](..\u002Fadd-function\u002FSKILL.md) | Adding new API wrapper functions |\n| [rest-api-patterns](..\u002Frest-api-patterns\u002FSKILL.md) | REST API implementation patterns |\n| [write-tests](..\u002Fwrite-tests\u002FSKILL.md) | Writing unit tests |\n| [code-style](..\u002Fcode-style\u002FSKILL.md) | Running linters and formatters |\n| [run-tests](..\u002Frun-tests\u002FSKILL.md) | Running pytest locally |\n| [github-repo-explore](..\u002Fgithub-repo-explore\u002FSKILL.md) | Finding reference implementations |\n",{"name":5,"description":7},"main","2ddf46109c1209ceffa88149f4631e7b2275f9a1",".claude\u002Fskills\u002Fplanning-with-files",204,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-13 04:54:42",{"source":8,"skillName":5,"commands":60,"prompt":70,"zipAvailable":71},[61,64,67],{"tool":62,"command":63},"npx","npx skills add microsoft\u002Fsemantic-link-labs --skill planning-with-files",{"tool":65,"command":66},"bunx","bunx skills add microsoft\u002Fsemantic-link-labs --skill planning-with-files",{"tool":68,"command":69},"pnpm","pnpm dlx skills add microsoft\u002Fsemantic-link-labs --skill planning-with-files","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplanning-with-files\u002FSKILL.md",true,[73],{"path":74,"resourceType":75,"resourceTypeDesc":76,"sizeBytes":77,"sourceHtmlUrl":78},"templates\u002Fcheckpoint-template.md","REFERENCE","参考文档",3110,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fplanning-with-files\u002Ftemplates\u002Fcheckpoint-template.md",[80,108,140,156,173,187],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":97,"publishedAt":45},"01M699GKE0WWT6YVHBS06KM8AH","write-tests","Guide for writing unit tests. Use this when creating tests to verify Python logic.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwrite-tests\u002FSKILL.md",[86,89,92],{"categoryNo":87,"categoryName":88,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":90,"categoryName":91,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":93,"categoryName":94,"taxonomyType":95,"taxonomyTypeDesc":96},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[98,99,100,31,101,29,102,103,104,105,38,106,107],"write tests","write","tests","unit","logic","writing","python","unit tests","guide","verify",{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":123,"publishedAt":45},"01M699GGVJHWCJNW68P08VWCMA","ui-styling","Guide for the visual style, structure, and shared building blocks used by Semantic Link Labs interactive UI tools (HTML widgets and anywidget-based widgets). Use this when adding a new interactive UI, modifying an existing one, or adding shared visual components.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fui-styling\u002FSKILL.md",[114,117,120],{"categoryNo":115,"categoryName":116,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":118,"categoryName":119,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":121,"categoryName":122,"taxonomyType":95,"taxonomyTypeDesc":96},"01JBSEEDCAT000000000000032","设计师",[124,125,126,38,127,128,129,106,130,131,132,133,134,135,136,137,138,31,139,29],"ui styling","ui","styling","visual","structure","html","interactive","Building Blocks","Tools","components","shared","widgets","style","visual style","blocks","Existing",{"skillNo":141,"name":142,"nameZh":6,"description":143,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":45},"01M699GEZ3YRK8PCPVZF4NEEWF","tom-operations","Guide for working with the TOM (Tabular Object Model) wrapper. Use this when modifying semantic models programmatically.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ftom-operations\u002FSKILL.md",[],[147,148,106,149,31,150,27,151,152,153,38,29,154,155],"operations","tom operations","tabular","object","semantic","models","Wrapper","model","semantic models",{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":160,"categories":161,"keywords":168,"publishedAt":45},"01M699GCWWBZM2XFNW5PTGRFJP","sql_to_dax","Guide for translating SQL aggregation expressions into DAX measures.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsql_to_dax\u002FSKILL.md",[162,165],{"categoryNo":163,"categoryName":164,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":166,"categoryName":167,"taxonomyType":95,"taxonomyTypeDesc":96},"01JBSEEDCAT000000000000033","数据分析师",[169,170,171,31,106,172],"sql","sql to dax","dax","aggregation",{"skillNo":174,"name":175,"nameZh":6,"description":176,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":179,"publishedAt":45},"01M699GAY10VVK66E4QGT94A93","run-tests","Guide for running pytest tests locally. Use this when running tests to verify code changes.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frun-tests\u002FSKILL.md",[],[100,180,181,31,182,38,106,107,183,184,185,186,29],"run","run tests","pytest","running tests","code","changes","running",{"skillNo":188,"name":189,"nameZh":6,"description":190,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":191,"categories":192,"keywords":197,"publishedAt":45},"01M699G8V718EXYE8BR7NX734G","rest-api-patterns","Guide for implementing REST API wrapper functions. Use this when adding new API wrappers or troubleshooting API calls.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fsemantic-link-labs\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frest-api-patterns\u002FSKILL.md",[193,194],{"categoryNo":163,"categoryName":164,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":195,"categoryName":196,"taxonomyType":95,"taxonomyTypeDesc":96},"01JBSEEDCAT000000000000030","开发工程师",[198,199,200,201,202,203,31,29,32,33,204,153,38,106,205],"REST","api patterns","rest api","rest api patterns","api","patterns","functions","troubleshooting"]